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Chapter 1 


Introduction 


1.1 Background 


The General Support subroutine library was developed at Queen Mary College (QMC) in London 
and is jointly owned by AMT and QMC. The library is a set of 93 routines which can be called 
from FORTRAN-PLUS. The contents of the library are based on those of the DAP Fortran library 
at QMC, which grew in response to user requests for specific routines. The routines were provided © 
by members of the DAP Support Unit (DAPSU) at QMC, or were written at the suggestion of 
DAPSU members, or were submitted by users themselves. Many of the algorithms used by these 
routines have been in regular use on a first generation DAP at QMC since 1980. 


1.2 Arrangement of Documentation 


The routines described in this manual are classified by chapter, arranged in a NAG-like manner, 
covering such areas as solution of linear equations, Fourier transforms, and so on. The next chapter 
in this manual provides a full listing of the contents of the library, chapter by chapter, and gives 
a brief description of the area covered by each routine. 


1.3. Validation 


Before being added to the library all routines undergo validation tests, designed and written at 
DAPSU. These tests have been collected together in a validation suite, which is used to check 
installation of the library. 
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1.4 FULL-FORM DOCUMENTATION Introduction 


1.4 Full-form Documentation 





The full description of each routine has eleven sections, covering the following areas: 


1 Purpose 





Specification 
Description 
References 
Arguments 

Error Indicators 
Auxiliary Routines 


Accuracy 


oO Oo NN DMD oO BP w pw 


Further Comments 


me 
So 


Keywords 


roy 
— 


Example 


1.4.1 Purpose 





The purpose of the routine is given, and where relevant, details of the area covered by the routine. 


1.4.2 Specification 


The calling sequence to be used when you invoke the routine. If the routine is written in FORTRAN- 
PLUS, Specification gives the declaration statements at the head of the routine; if the routine is 
written in APAL, the equivalent statements are given. 


1.4.3 Description 


The description of the algorithm used by the routine is given. 


1.4.4 References 


Any references used in connection with the routine are given. 


1.4.5 Arguments 


The significance of each argument used by the routine is explained. 
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Introduction 1.5 ACCESS TO THE LIBRARY 


1.4.6 Error Indicators 


' The significance of any error indicators returned by the routine is explained. 


1.4.7 Auxiliary routines . 


The names of any auxiliary routines used by the routine are given. The auxiliary routines are kept 
in the same library as the subroutine library routines but are not, in general, available to users. 


1.4.8 Accuracy 


Some indication is given of the expected accuracy of any result returned by the routine as a result 
of the method used to calculate it. No information is given about results with respect to the 
word length used; for such information have a look at the routines in chapter 12 (X02 — Machine 
constants). 


1.4.9 Further Comments 


Any information which does not fall under any other heading is included here. 


1.4.10 Keywords 


This section is intended for use with an information retrieval system and gives a list of sub jects to 
which the operation of the routine may be relevant. 


1.4.11 Example 


An example program is given (both Host and DAP programs) for each of the routines, showing 
the use of the routine and any expected results. 


WARNING 


You should follow closely the specification of the calling sequence given in section 2 of the details 
of each routine in the following chapters, otherwise you may get unexpected results. 


1.5 Access to the Library 


The subroutine library is linked in at the consolidation stage of the compiling process. For more 
details than are included below, see the relevant AMT publication: Program Development Under 
UNIX (man003), or Program Development Under VAX/VMS (man004). 
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1.6 OTHER AMT SUBROUTINE LIBRARIES Introduction 


1.5.1 Using the library under UNIX 


The library resides within the UNIX system as: 
/usr/lib/dap/sulib.dl 

and you can use it in a call to dapa or dapf by means of the -1 flag, as in: 
dapf -o myfile.dd myfile.df -1 sulib 


This call will compile the DAP section myfile.df, linking in any routines from the library and 
produce a DOF file myfile.dd. 


1.5.2 Using the library under VAX /VMS 


The library resides within the VMS system as: 
SYS$LIBRARY : GSLIB.DLB 

and you can use it in a call to DLINK using the /LIBRARY qualifier, as in: 
$ DLINK MYFILE,SYS$LIBRARY :GSLIB/LIBRARY 


This call links the DAP object code in file MYFILE.DOB with any library routines you might 
specify in your source code, producing an executable DAP program in file MYFILE.DEX. 


Alternatively, you can use the DAP_ LIBRARY logical name, as in: 
$ DEFINE DAP_LIBRARY SYS$LIBRARY :GSLIB 


This call will cause the library to be searched automatically in all subsequent DLINK operations. 
If you use the library frequently, you may find it convenient to include the above line in your 
LOGIN.COM file.. If there are several DAP users on your system, your system manager could 
include the line: 


$ DEFINE/SYSTEM DAP_LIBRARY SYS$LIBRARY:GSLIB 


in the system startup command file, to give all users automatic access to the library. 


1.6 Other AMT subroutine libraries 


This General Support subroutine library forms one of a series of libraries available from AMT. 
Other libraries include: 


e Low level graphics library 
e Signal processing library 


e Image Processing library 


details of which can be obtained from your local AMT representative. 
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Chapter 2 


GSLIB quick-reference catalogue 


Listed below are the groups of subroutines in release 1 of GSLIB, the General Support subroutine 
library, and the subroutines in each group; each group is allocated a chapter in this manual. Release 
1 of the library is targetted at the DAP 500 series of machines, those with an edge size of 32. 


You may find this chapter helpful in the initial selection of suitable routines for the job in hand. 


Chapter 3: AO3 — Variable precision arithmetic 


1 A03_ADD_PLANES_I1 adds bit planes together by performing an addition of n 
consecutive bits under each processing element. It returns the result of this addition as an 
INTEGER*1 MATRIX. Any overflow past bit 7 is discarded and the result is given modulo 
128. 


Chapter 4: C06 — Summation of series, including fast Fourier 
transformations 


1 CO6_LFT_LV performs a one dimensional finite Fourier transform of 1024 complex 
points. 


2 CO6_LFT_ESS calculates the two dimensional discrete Fourier transform of 32? com- 
plex points. 


Chapter 5: F01 — Matrix operations, including inversion 


1 FO1-G_MM performs a general matrix multiply of two matrices A and B where A is a 
P by Q matrix and B is a Q by R matrix with P, Q and R in the range 1 to 32. 


2 FO1_M_INV calculates, in place, the inverse of a given N by N matrix with N in the 
range 1 to 32. 


3 FO1-MM-_STRASSEN uses Strassen’s algorithm to multiply two (partitioned) 64? 


matrices. 


Chapter 6: F02 — Eigenvalues and eigenvectors 
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GSLIB quick-reference catalogue 


FO02_ALL_EIG_VALS_TD_LV finds all the eigenvalues of a symmetric tridiagonal 


matrix of order up to 1024 using Sturm sequences. 


FO2_ALL_EIG_VALS_TD_ES finds all the eigenvalues of a symmetric tridiagonal 


matrix of order up to 32 using Sturm sequences. 


F0O2_EIG_VALS_TD_LV finds up to 32 selected eigenvalues of a symmetric tridi- 
agonal matrix of order up to 1024 using Sturm sequences. 


F0O2_JACOBI calculates the eigenvalues and eigenvectors of a real symmetric matrix. 
The method is based on the classical Jacobi algorithm using plane rotations. 


Chapter 7: F04 — Simultaneous linear equations 


1 


F04_ BIGSOLVE solves large sets of linear equations. The maximum size of the system 
depends on the size of the DAP store. The matrix of the coefficients of the equations is of 
size SIZE by SIZE and the right hand side is assumed to be held in column SIZE+1. 
The whole matrix is held in the DAP partitioned in DAPSIZE blocks. This routine is 
not recommended for systems of order 32 or less — in this case, you should use the routine 
F04.GJN_LE_ES. 


“F04_GJ_NLE_ES solves for « the system of linear equations Az = b, where A is a 


non-sparse matrix of order N (in the range 1 to 32), using the Gauss Jordan method. 


F04_QR_GIVENS_SOLVE solves for z the linear system Az = b, where A is an 
N by N matrix with 2 < N < 33. The routine may be used to solve up to 32 different right 
hand side vectors 6 simultaneously. 


F04.TRIDS_ES returns the solution of a tridiagonal linear system of equations of 
order up to 32. It finds vector x, where: 


Mz=y 


and M is a tridiagonal matrix. 


F04_TRIDS_ES_SQ returns the solution of a set of up to 32 tridiagonal linear systems 
of equations each of order up to 32. It solves up to 32 systems of the form: 


Mer=y 


where M is a tridiagonal matrix. 


F04_TRIDS_LV returns the solution of a tridiagonal linear system of equations of 
order up to 1024. It finds vector z, where: 


Me=y 


and M is a tridiagonal matrix. 


Chapter 8: G05 — Random numbers 


1 


G05_MC_ BEGIN sets the basic generator routine Z-G05. MC-_INT to an initial state. 
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GSLIB quick-reference catalogue 


2 G0O5_MC_I4 returns an INTEGER*4 MATRIX containing 1024 pseudo-random integer 
numbers taken from a uniform distribution between 0 and 22! — 1. 


3 G05_MC_I8 returns an INTEGER*8 MATRIX containing 1024 pseudo-random integer 
numbers taken from a uniform distribution between 1 and 2°9 — 1. 


4 GO5_.MC_NORMAL_R4 returns a REAL*4 MATRIX of 1024 normal pseudo- 
random variates from the distribution N (0,1). 


5 GO5_MC_R4 returns a REAL*4 MATRIX of 1024 pseudo-random real numbers taken 
from a uniform distribution between 0 and 1. 


6 G0O5_MC_R8& returns a REAL*8 MATRIX of 1024 pseudo-random real numbers taken 
from a uniform distribution between 0 and 1. 


7 G05_.MC_REPEAT sets the basic generator routine Z-G05.MC_INT to a repeatable 
initial state. 


Chapter 9: H — Operations research, graph structures, networks 


1 HO1_L_ASSIGN solves the linear assignment problem with a minimum objective 
function and a real cost matrix of order N by N, where N <= 32. 


Chapter 10: JO6 — Plotting 


1 JO6_CHAR_CONT returns a character matrix containing a rough contour map of a 
real matrix. You can control the number of contours and contour levels. 


2 JO6_ZEBRA_CHART returns a contour map of a real matrix suitable for output to 
a printing device. The output is called a ZEBRA chart as it consists of alternating bands of 
blanks and a given character. 


Chapter 11: MO1 — Sorting 


1 M01_BSORT_LV is based on bitonic sorting. Data is sorted according to a key, or 
the key alone may be sorted. 


2 MO1INV_PERMUTE_COLS permutes the first M columns of a matrix ac- 
cording to a permutation vector (IV). The routine is equivalent to the FORTRAN-PLUS 
statements: 


DO 10I1=1,M 
10 A-PERMUTED(,IV(I) ) = A(,1) 


3 M01_INV_PERMUTE_LV_ 32 permutes the values in an INTEGER*4 or REAL*4 
matrix using an INTEGER*4 matrix key. The result is written to a new matrix and the orig- 
inal data is unaffected. The data shuffling implemented is ANSWER (KEY(I)) = START 
(I), for I = 1, 1024, using long vector indexing. Hence the key matrix must contain values 
in the range 1 — 1024, but the values need not be distinct. 
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GSLIB quick-reference catalogue 


M01_INV_PERMUTE_ROWS permutes the first M rows of a matrix according 
to a permutation vector (IV). The routine is equivalent to the FORTRAN-PLUS statements: 


DO 101=1,M 
10 A.PERMUTED(,IV(I) ) = A(,I) 


~M01.PERMUTE_COLS permutes the first M columns of a matrix according to a 


permutation vector (IV). The routine is equivalent to the FORTRAN-PLUS statements: 


DO 10I1=1,M 
10 A.PERMUTED(,I) = A(,IV(I)) 


M01_PERMUTE_LV_32 permutes the values in an INTEGER*4 or REAL*4 ma- 
trix using an INTEGER*4 matrix key. The result is written to a new matrix and the original 
data is unaffected. The data shuffling implemented is ANSWER (I) = START (KEY(D), 
for I = 1,1024, using long vector indexing. Hence the key matrix must contain values in the 
range 1 — 1024, but the values need not be distinct. 


M01_PERMUTE_ROWS permutes the first M rows of a matrix according to a 
permutation vector (IV). The result is equivalent to the FORTRAN-PLUS statements: 


DO 101=1,M 
10 A.PERMUTED(I,) = A(IV(I),) 


M01_SORT_V_14 -sorts the first N elements of an integer vector into ascending or 
descending order. The permutation required to perform the sort is returned to the calling 
routine. 


M01_SORT_V_R<4 sorts the first N elements of a real vector into ascending or de- 
scending order. The permutation required to perform the sort is returned to the calling 
routine. 


Chapter 12: S — Special functions 


1 


S04_ARC_COS returns the value of the inverse cosine function arccos (x) for a matrix 
argument. The result lies in the range (0, 7]. 


S04. ARC_SIN returns the value of the inverse sine function arcsin (x) for a matrix 
argument. The result lies in the range [—72/2, 7/2]. 


S04_ATAN2_M_ is a matrix function similar to the standard FORTRAN ATAN2 
function. It calculates arc-tangent(matrix-1/matrix-2), and returns a matrix of values in the 
range —7 to 7, in the correct quadrant, and with divide-by-zero errors avoided. If a zero 
divided by zero is attempted then a zero is returned. 


$04_ATAN?2-V is a vector function similar to the standard FORTRAN ATAN?2 func- 
tion. It calculates arc-tangent(vector-1/vector-2), and returns a vector of values in the range 
—7 to 7, in the correct quadrant, and with divide-by-zero errors avoided. If a zero divided 
by zero is attempted then a zero is returned. 


S04_COS_INT returns the value of the cosine integral C;z for a matrix argument. 
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10 


S04_MOD_BES_IO returns the value of the modified Bessel function I0 for a matrix 
argument. 


S04_MOD_BES_I1 returns the value of the modified Bessel function I1 for a matrix 
argument. 


S04_SIN_INT returns the value of the sine integral S;x for a matrix argument. 
S15_ERF returns the value of the error function. 


S15. ERFC returns the value of the complement of the error function. 


Chapter 13: X01 — Mathematical constants 


1 


XO1_PI determines the value of x for any of the real precision lengths available on the 
DAP. 


Chapter 14: X02 — Machine constants 


1 


X02_EPSILON determines the smallest positive real (EPS) such that 1.0+EPS differs 
from 1.0, for any of the real precision lengths available on the DAP. 


X02_MAXDEC determines the value of MAXDEC for the different precision lengths 
available on the DAP. MAXDEC is the maximum number of decimal digits which can be 
represented accurately over the whole range of floating point numbers. 


X0O2_MAXINT determines the value of MAXINT for the different precision lengths 
available on the DAP. MAXINT is the largest integer such that MAXINT and -MAXINT 
can both be represented accuratetly. 


X02_MAXPW2 determines the value of MAXPW2 for the different precision lengths 
available on the DAP. MAXPW2 is the largest integer power to which 2.0 may be raised 
without overflow. 


X02_MINPW2 determines the value of MINPW2 for the different precision lengths 
available on the DAP. MINPW2 is the largest negative integer power to which 2.0 may be 
raised without underflow. 


X02_RMAX determines the largest real (RMAX) such that RMAX and -RMAX can 
both be represented exactly, for any of the real precision lengths available on the DAP. 


X0O2_RMIN determines the smallest real (RMIN) such that RMIN and -RMIN can 
both be represented exactly, for any of the real precision lengths available on the DAP. 


X02_TOL determines the value of TOL (= RMIN/EPSILON) for any of the precision 
lengths available on the DAP. 
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Chapter 15: X05 — Other utilities 


1 


10 


11 


12 


10 


X05_ALT_LV produces a long vector of alternating groups of N false values followed 
by N true values and so on, until all components of the vector have a value. If the value of 
N lies outside the range 1 to 1024 all components will have the value false. 


X05_CRINKLE effects a transformation in data storage format for vertical mode data 
occupying an array of matrices — from ‘sliced’ to ‘crinkled’ storage. 


X05_EAST_BOUNDARY returns a logical matrix containing at most one .TRUE. 


in each row corresponding to the last .TRUE. (if any) in each row of the logical matrix 
parameter. The routine is equivalent to the FORTRAN-PLUS code: 


DO 101 = 1, 32 

IF (NOT. ANY (LM(I,))) GOTO 10 

KM (I,) = REV(FRST (REV (LM (1, )))) 
10 CONTINUE 


X05_E_MAX_PC returns a logical matrix whose it* row has the value .TRUE. in 
the position(s) corresponding to the position(s) in the i** row of the real matrix argument 
holding the maximum value in that row, and .FALSE. elsewhere. 


X05_E.MAX_PR returns a logical matrix whose i** column has the value TRUE. in 
the position(s) corresponding to the position(s) in the i** column of the real matrix argument 
holding the maximum value in that column, and .FALSE. elsewhere. 


X05_E_MAX_VC returns a real vector whose i” component is the maximum value 
in the i** row of the real matrix argument. 


X05_E_MAX_VR returns a real vector whose i** component is the maximum value 
in the i** column of the real matrix argument. 


X05_E_MIN_PC returns a logical matrix whose i** row has the value .TRUE. in 
the position(s) corresponding to the position(s) in the it* row of the real matrix argument 
holding the minimum value in that row, and .FALSE. elsewhere. 


X05. E_MIN_PR returns a logical matrix whose i* column has the value TRUE. in 
the position(s) corresponding to the position(s) in the i** column of the real matrix argument 
holding the minimum value in that column, and .FALSE. elsewhere. 


X05. E.MIN_VC returns a real vector whose it” component is the minimum value in 
the z** row of the real matrix argument. 


X05_E_MIN_VR returns a real vector whose it* component is the minimum value in 
the i** column of the real matrix argument. 


X05. EXCH_P exchanges L planes starting at X with L planes starting at Y under 


activity control indicated by M. The planes are exchanged in increasing order; you are 
cautioned about the strange effects which will occur if the two sets of planes overlap. 
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14 


15 


16 


17 


18 


19 


20 


21 


22 


23 


24 


X05_GATHER_V_ 32 assigns to the components of a vector the values of those 
components of a vector array designated by corresponding components of an indexing vector. 
The index values are interpreted as reduced rank indices to the vector array. 


X05_I_-MAX_PC returns a logical matrix whose i‘* row has the value .TRUE. in the 
position(s) corresponding to the position(s) in the i‘* row of the integer-matrix argument 
holding the maximum value in that row, and .FALSE. elsewhere. 


X05_I.MAX_PR returns a logical matrix whose i** column has the value .TRUE. 
in the position(s) corresponding to the position(s) in the 7** column of the integer matrix 


argument holding the maximum value in that column, and .FALSE. elsewhere. 


X05_I.MAX_VC returns an integer vector whose i** component is the maximum 
value in the i*" row of the integer matrix argument. 


X05_I.MAX_VR_ returns an integer vector whose i#* component is the maximum 


- value in the i** column of the integer matrix argument. 


X05_I.MIN_PC returns a logical matrix whose i** row has the value .TRUE. in the 
position(s) corresponding to the position(s) in the i** row of the integer matrix argument 
holding the minimum value in that row, and .FALSE. elsewhere. 


X05_I_MIN_PR _ returns a logical matrix whose i** column has the value . TRUE. 
in the position(s) corresponding to the position(s) in the i** column of the integer matrix 
argument holding the minimum value in that column, and .FALSE. elsewhere. 


X05_I_ MIN-_VC returns an integer vector whose i** component is the minimum value 
in the i" row of the integer matrix argument. 


X05_I_MIN_VR returns an integer vector whose i** component is the minimum value 
in the 7** column of the integer matrix argument. 


X05_LOG2 returns the value: 
[log(N—1)]+1 


where square brackets indicate ‘integer part of’, and N is the input argument. The routine 
returns the number of steps required in a logo, recursive doubling, algorithm. 


X05. LONG_INDEX generates an integer matrix whose i‘ element in long vector 
order is ( + N — 1), where N is a parameter to the routine. 


X05_NORTH.-BOUNDARY returns a logical matrix containing at most one 


-TRUE. in each column corresponding to the first .TRUE. (if any) in each column of the 
logical matrix parameter. The routine is equivalent to the FORTRAN-PLUS code: 


DO 101 = 1, 32 
IF (NOT. ANY (LM(,I))) GOTO 10 
KM (,I) = FRST (LM (,1)) 

10 CONTINUE 
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X05. PATTERN produces four user-selectable patterns, each of which is returned as 
a logical matrix. The four patterns available are: 


0 ~ The main diagonal 
1 - The minor diagonal 
2 —- A matrix, the rows of which correspond to the rows generated by ALTC 


3 ~ The unit lower triangular matrix 


X05_SCATTER_V_ 32 takes components of a vector and assigns the values to com- 
ponents of a vector array designated by corresponding components of an indexing vector. 
The index values are interpreted as reduced rank indices to the vector array. 


X05_SHLC_LV performs a cyclic long vector shift to the left on up to 128 bit planes. 
X05.SHLP-_LV performs a planar long vector shift to the left on up to 128 bit planes. 


X05.SHORT_INDEX generates an integer vector whose i** element is (i + N - 1), 


where N is a parameter to the routine. 
X05_SHRC_LV performs a cyclic long vector shift to the right on up to 128 bit planes. 


X05_.SHRP_LV performs a planar long vector shift to the right on up to 128 bit 
planes. 


X05_.SOUTH_. BOUNDARY returns a logical matrix containing at most one 


-TRUE. in each column corresponding to the last .TRUE. (if any) in each column of the 
logical matrix parameter. The routine is equivalent to the FORTRAN-PLUS code: 


DO 101 =1, 32 

IF (.NOT. ANY (LM (,I))) GOTO 10 

KM (,1) = REV(FRST (REV (LM (,1)))) 
10 CONTINUE 


X05_STRETCH_4 stretches the first quarter of a real matrix A (considered as a long 
vector), such that each element is repeated four times consecutively. 


X05_STRETCHL8 stretches the first eighth of a real matrix A (considered as a long 


’ vector), such that each element is repeated eight times consecutively. 


X05.STRETCHL_N stretches the first NtP of a real matrix A (considered as a long 
vector), such that each element is repeated N times consecutively, N being 2 raised to a 
positive integer power. 


X05_-SUM.LEFT_1I2 takes as input the long vector A (an INTEGER*2 vector) and 


returns an INTEGER*2 long vector each of whose elements is the sum of all the elements 
on the left of, but not including, the corresponding element of A. # 
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37 X05_SUM_RIGHT_1I2 takes as input the long vector A (an INTEGER*2 vector) 
and returns an INTEGER*2 long vector each of whose elements is the sum of all the elements 
on the right of , but not including, the corresponding element of A. 


38 XO5_UNCRINKLE effects a transformation in data storage format for vertical mode 
data occupying an array of matrices — from ‘crinkled’ to ‘sliced’ storage. 


39 X05_WEST_BOUNDARY returns a logical matrix containing at most one .TRUE. 
in each row corresponding to the first .TRUE. (if any) in each row of the logical matrix 
parameter. The routine is equivalent to the FORTRAN-PLUS code: 


DO 101=1, 32 
IF (.NOT. ANY (LM, (I,))) GOTO 10 
KM (I,) = FRST(LM(I,)) 

10 CONTINUE 
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Chapter 3 


A03 — Variable precision 


arithmetic 
Contents: 
Subroutine Page 


A03_ADD. PLANES_I1 16 
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3.1 A03_ADD.PLANES_TIi A03 — Variable precision arithmetic 


sve I A03_ADD_PLANES_I1 . release 1 


16 


Purpose 


A03_ADD_PLANES_Ii adds bit planes together, that is, it performs an addition of n con- 
secutive bits of each PE. 


A03_ADD_PLANES_I1 returns the result of this addition so that the corresponding element 
of the result is the sum of the n consecutive bits of the corresponding PE. 


The result is calculated to an accuracy of integer*1, therefore any overflow past bit 7 is 
thrown away and the result is modulo 128. 


Specification 


INTEGER*1 MATRIX FUNCTION A03_ADD_PLANES_I1 (STARTPLANE , 
+ NRPLANES) 

INTEGER NRPLANES 

<any type> STARTPLANKE(,) 


Description 


The DAP can add the contents of a store plane and the Q and C planes simultaneously ; 
this routine uses that ability to add pairs of planes. The resulting carry is then rippled up 
the answer. 


References 


None 


Arguments 
STARTPLANE - <any type> MATRIX 


On entry STARTPLANE contains the address of the first plane to be added. The 
function adds NRPLANES consecutive planes starting at STARTPLANE.-START- 
PLANE may, in FORTRAN-PLUS, be any variable represented by a plane address. 
None of the planes added are changed by the function, but you are warned against 
allowing the destination of the result to overlap the planes to be added. If you do 
try overlapping the planes, the program will still work, but you will have overwritten 
your arguments before you accessed them! 


NRPLANES - INTEGER 
On entry NRPLANES specifies the number of planes to be added. Unchanged on exit. 


Error Indicators 


None 


Auxiliary Routines 


None 


Accuracy 


The results are calculated mod 128 - overflow is not detected. 
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9 Further Comments 





None 


10 Keywords 


Bit summation, integer addition. 


11 Example 


The example adds the bit planes which define a long index vector, thus counting the number 
of bits set .TRUE. in the binary representation of the integers 0 to 1023. 


Host program 


PROGRAM MAIN 


INTEGER IM(1024) 
COMMON /IM/IM 


CALL DAPCON(?’ ent.dd?’) 
CALL DAPENT(? ENT?) 
CALL DAPREC(?IM? ,IM, 1024) 


WRITE(6, 1000) 
1000 “FORMAT(6X,’I’,3X,’No. of bits set’//) 
DO 10 II=1,1024 


© ; I=II-1 
' 40» WRITE(6,2000) I,IM(IZ) 
2000 FORMAT(I7,10X,12) 


CALL DAPREL 
STOP 
END 


DAP program 


ENTRY SUBROUTINE ENT 
INTEGER*1 IM1(,) 
INTEGER IM(,) 
LOGICAL LM(, ,32) 
COMMON /IM/IM 
EQUIVALENCE (IM,LM) 


EXTERNAL INTEGER*1 MATRIX FUNCTION AO3_ADD_PLANES I1 
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CALL XOSLONGINDEX(IM,0) 
IM1=A03_ADD_PLANES_Ii(LM(, ,21),10) 
IM=IM1 

CALL CONVMFI(IM) 





RETURN 
END 


Results ~ 


I No. of bits set 


0 0 
1 1 
2 1 
3 2 
1020 8 
1021 9 
1022 9 
1023 10 
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C06 _ Summation of series 


(including fast fourier transformations) 


Contents: 
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C06. FFT_ESS 20 
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4.1 CO6_FFT_ESS C06 — Summation of series 


4.1 C06_FFT_ESS release 1 


20 


Purpose 


C06. FFT_ESS calculates the two dimensional discrete Fourier transform of 32 x 32 complex 
points. 


Specification 


SUBROUTINE C06_FFT_ESS(X , Y , INVERS , FIRST) 
REAL X(,) ? Yi 
LOGICAL INVERS , FIRST 


Description 


The 2D transform is calculated by performing independent sets of row and column 32-point 
transforms. 


The data is then in bit reversed order independently in rows and columns and a final shuffle 
is performed to reorder the data. 


For a description of the general theory of FFTs see [1]. 


References 
[1] BRIGHAM E.O. 
The Fast Fourier Transform: Prentice-Hall, 1974 


Arguments 
X ~ REAL MATRIX 


On entry X contains the real part of the data to be transformed. On exit X contains the 
real part of the transformed data. 


Y ~ REAL MATRIX 


On entry Y contains the imaginary part of the data to be transformed. On exit Y 
contains the imaginary part of the transformed data. 


INVERS — LOGICAL 
If INVERS is set to .FALSE. the transform: 


Xjeti¥in = D7) (Amn +iBmnn exp (Zain) a cayen) 


is calculated, where j = 1, 2,... , 32; k = 1, 2,... , 32 and the summations are also 


overm=1,2,... ,32andn=1,2,... , 32; and where i = /—1. 
If INVERS is set to .TRUE. the transform: 


Amn+iBmn = YY (XjetYje)exp (2 ~ NG Aa) 4 (as Mt = ») 
j ok 


is calculated, where m = 1, 2,... , 32; n = 1, 2, ... , 32 and the summations are also 
overj = 1,2,... ,32andk=1,2,... , 32; and where i = /—1. 
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11 


FIRST —- LOGICAL 


If FIRST is set to .TRUE. the exponential coefficients for the transform are calculated. 
Consequently FIRST must be set to .TRUE. the first time this routine is called within 
a program, but may be set to .FALSE. for all subsequent calls. 


Error Indicators 


None 


Auxiliary Routines 


This routine calls the DAP library routines Z.CO6. F2DCOEFF, Z.C06. ROWFFT, 
Z.C06.COLFFT and Z_C06.F2DBREV. 


Accuracy 


Accuracy will be data dependent. Some indication of the accuracy may be obtained by 
performing a subsequent inverse transform and comparing the results with the original data. 


Further Comments 


This routine uses a common block with the name CCO6FFTESSQ. Consequently the user 
program must not use a common block with this name. 


Keywords 


Fast Fourier Transform 


Example 


The example given sets up an initial array of complex points in which the real and imaginary 
parts are simple functions of a real variable. A forward transform is then performed followed 
by a back transform of the transformed data. The first 32 complex values of the first row of 
the initial data, transformed data and back transformed data are printed. 


Host program 


PROGRAM HTFFTESS 
REAL X(32,32) ,¥(32,32) ,XT(32,32) , YT(32,32) ,XB(32,32) , YB(32,32) 
COMMON /BDATA/X,Y,XT,YT,XB, YB 
CALL dapcon(’tfftess.dd’) 
CALL dapent(’TFFTESS’ ) 
CALL daprec(’BDATA’ ,X,6*1024) 
DO 100 i=i,1 
WRITE(6 , 6001) 
WRITE(6 , 6002) 
$(X(J,i),Y(J,I),XT(J,1) ,YT(J,I) ,XB(J,1I),YB(J,1) , J=1, 32) 
6001 FORMAT(2X,’DATA TO BE TRANSFORMED’ ,9X,’TRANSFORMED DATA’ 
$9X,’BACK TRANSFORMED DATA’//3(9X,’REAL’, 9X,?IMAG’) /) 
6002 FORMAT(6(1X,F12.6)) 
100 CONTINUE 
CALL daprel 
STOP 
END 


General Support library man010.02 21 


4.1 CO6_FFT_ESS C06 ~ Summation of series 


DAP program 





ENTRY SUBROUTINE TFFTESS 
REAL X(,),Y(,),XT(,), YT(,),XB(,), YB(,) 
INTEGER IM(,) 

LOGICAL INVERS, FIRST 

COMMON /BDATA/X,Y,XT,YT,XB, YB 

CALL LONG_INDEX (IM) 

X=6 .28318*(IM-1)/1023.0 

Y=SIN(X) 

X=COS(X)*COS(X) 

XT=X 

YT=Y 

INVERS=.FALSE. 

FIRST=. TRUE. 

CALL CO6_FFT_ESS(XT, YT, INVERS ,FIRST) 
XB=XT 

YB=YT 

FIRST=. FALSE. 

INVERS=. TRUE. 

CALL CO6_FFT_ESS(XB, YB, INVERS , FIRST) 
XB=XB/1024.0 

YB=YB/1024.0 

CALL CONVMFE(X) 

CALL CONVMFE(Y) 

CALL CONVMFE(XT) 

CALL CONVMFE(YT) 

CALL CONVMFE(XB) 

CALL CONVMFE(YB) 

RETURN 

END 
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Results 
DATA TO BE TRANSFORMED TRANSFORMED DATA BACK TRANSFORMED DATA 
REAL IMAG REAL IMAG REAL IMAG 
1.000000 . 000000 512.499512 -.000001 1.000000 .000000 
. 999962 -006142 .029227 -.002885 .999962 . .006142 
. 999848 .012284 -014964 -.002954 . 999849 .012284 
- 999661 -018425 .009909 -.002994 . 999661 .018425 
. 999397 .024565 .007302 -.003027 . 999397 .024565 
- 999057 - 030705 .005657 -.002998 . 999057 .030705 
.- 998642 . 036843 -004522 -.003013 . 998642 . 036843 
. 998152 .042980 .003741 -.003100 .998152 .042980 
. 997588 .049116 -003037 -.003032 . 997588 .049115 
- 996947 .055249 .002486 -.003049 . 996948 .055249 
- 996232 -061381 .002015 - .003077 . . 996232 .061380 
. 995442 .067510 .001615 -.003032 .995441 .067510 
. 994578 . 073636 .001249 -.003026 . 994577 .073636 
- 993638 .079760 -000901 -.003026 . 993638 .079760 
. 992624 . 085881 -000625 -.003057 . 992624 . 085881 
. 991536 .091999 -000311 -.003093 . 991536 .091999 
. 990374 .098113 .000000 -.003080 . 990374 .098113 
.989138 . 104223 -.000266 -.003058 . 989137 . 104223 
. 987827 . 110329 -.000591 -.003060 . 987828 . 110329 
© . 986444 . 116432 -.000956 -.003115 . 986444 . 116432 
. 984986 . 122530 -.001285 -.003113 . 984986 . 122530 
. 983456 . 128623 -.001659 -.003107 . 983457 . 128623 
-981852 134711 -.002083 -.003071 . 981853 134711 
. 980176 . 140795 -.002545 -.003089 .980176 . 140795 
. 978428 . 146873 -.003098 -.003093 . 978428 . 146873 
. 976608 . 152945 -.003736 -.003047 . 976608 . 152945 
.974715 . 159012 -.004658 -.003119 .974715 . 159012 
~972751 . 165073 -.005815 -.003132 .972751 . 165073 
.970715 .171127 -.007510 -.003113 .970715 .171127 
- 968608 177175 -.010330 -.003156 - 968608 .177175 
. 966431 . 183217 -.015892 -.003190 . 966431 . 183217 
- 964184 .189251 -.033177 -.003261 . 964183 .189251 
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4.2 C06_ FFT_LV release 1 


1 Purpose 


C06. FFT_LV performs a one dimensional finite Fourier transform of 1024 complex points. 


2 Specification 


SUBROUTINE C06. FFT_LV(X , Y , INVERS , FIRST) 
REAL X(,) , Y(,) 
LOGICAL INVERS , FIRST 


3 Description 


The data is considered as 1024 complex points in long vector order, and the transform is 
calculated by performing linked row and column transforms. The first step is to calculate 
32-point transforms along each row of complex data. The results of the row transforms are 
multiplied by a second set of exponential factors and then 32-point transforms are calculated 
along each column in a similar way to the row transforms but using different exponential 
factors. The exponential factors are set up in such a way as to ensure that the row and 
column transforms are linked correctly to give the required 1D transform. The final step 
re-orders the data which is in bit reversed order. 


For a description of the general theory of FFTs see [1]. 


4 References 
[1] BRIGHAM E.O. 
The Fast Fourier Transform: Prentice-Hall, 1974 


5 Arguments 
X —- REAL MATRIX 


On entry X contains the real part of the data to be transformed. On exit X contains the 
transformed real part of the data. 


Y - REAL MATRIX 


On entry Y contains the imaginary part of the data to be transformed. On exit Y 
contains the transformed imaginary part of the data. 


INVERS - LOGICAL 
If INVERS is set to .FALSE. the transform: 


1024 
Fann : (j -1)(k-1) 
Xj+tY; = 2, (AvtiBs exp (2ni¥=E— 


is calculated, where j = 1, 2,... , 1024 and the summation is over k = 1, 2,... , 1024; 
and where i = /—1. 


24 man010.02 AMT 

















C06 - Summation of series 4.2 C06. FFT_LV 


If INVERS is set to .TRUE. the transform: 


1024 é 
oat oe me Ag=A\(k =) 
Apt+iB, = 2% +1Y;)exp (-20 Ter 


is calculated, where k = 1, 2,... , 1024 and the summation is over j = 1, 2,... , 1024; and 
where i = /—1. 


The argument is unchanged on exit. 


FIRST — LOGICAL 


10 


ll 


If FIRST is set to .TRUE. the exponential coefficients for the transform are calculated. 
Consequently FIRST must be set to .TRUE. the first time this routine is called within 
a program,but may be set to .FALSE. for all subsequent calls. 


The argument is unchanged on exit. 


Error Indicator 


None 


Auxiliary Routines 


The routine calls the DAP library routines Z_-CO6FFT1IDCOEFF, Z_COSROWFFT, 
Z.CO6COLFFT, Z.CO6FFTIDBREV. 


Accuracy 


Accuracy will be data dependent. You can get some idea of the accuracy by carrying out 
the transform, then carrying out the inverse transform and comparing the results with the 
original data. 


Further Comments 


The routine uses a common block with name CCO6FFTLV. Consequently your program must 
not use a common block with this name. 


Keywords 


Fast Fourier Transform 


Example 


The example given sets up initial data in which the real and imaginary parts are simple func- 
tions of a real variable. A forward transform is then performed, followed by a back transform 
of the transformed data. The first ten complex values of the initial data, transformed data 
and back transformed data are printed in long vector order. 
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Host program 


6001 
6002 
6003 
6004 


PROGRAM HTFFTLV 
REAL X(32,32) ,¥(32,32) ,XT(32,32) ,YT(32,32) ,XB(32,32) , YB(32,32) 
COMMON /BDATA/X,Y,XT,YT,XB,YB 


CALL DAPCON(’tfftlv.dd’) 

CALL DAPENT(?TFFTLV’ ) 

CALL DAPREC(’BDATA’ ,X,6*1024) 

WRITE(6 , 6001) 

WRITE(6,6002) (X(I,1),¥(I,1),I=1,10) 

WRITE(6 , 6003) 

WRITE(6,6002) (XT(I,1),YT(I,1),I=1,10) 

WRITE(6 , 6004) 

WRITE(6,6002) (XB(I,1),YB(I,1),I=1,10) 

FORMAT(2X,’DATA TO BE TRANSFORMED’//7X, REAL’ ,9X,?IMAG’/) 
FORMAT(2(1X,F12.6)) 

FORMAT(//2X,’ TRANSFORMED DATA’//7X, ?REAL’ ,9X, ?IMAG’/) 
FORMAT(//2X,?BACK TRANSFORMED DATA’//7X, REAL’ ,9X, IMAG’) 
STOP 

END 


DAP Program 


ENTRY SUBROUTINE TFFTLV 

REAL X(,),¥(,),XT(,),YT(,),XB(,), YB(,) 
INTEGER IM(,) 

LOGICAL INVERS,FIRST 

COMMON /BDATA/X,Y,XT,YT,XB,YB 

CALL LONG_INDEX(IM) 

X=6 . 28318*(IM-1)/1023.0 

Y=SIN(X) 

X=COS(X)*#COS(X) 

XT=X 

YT=Y 

INVERS=.FALSE. 

FIRST=.TRUE. 

CALL CO6_FFT_LV(XT, YT, INVERS , FIRST) 
XB=XT 

YB=YT 

FIRST=.FALSE. 

INVERS=.TRUE. 

CALL CO6_FFT_LV(XB, YB, INVERS, FIRST) 
XB=XB/1024.0 

YB=YB/1024.0 
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CALL CONVMFE(X) 
CALL CONVMFE(Y) 
CALL CONVMFE(XT) 
CALL CONVMFE(YT) 
CALL CONVMFE(XB) 
CALL CONVMFE(YB) 
RETURN 

END 





Results 


DATA TO BE TRANSFORMED 


REAL IMAG 
1.000000 .000000 
- 999962 006142 
- 999848 012284 
- 999661 .018425 
. 999397 024565 
. 999057 .030705 
- 998642 - 036843 
-998152 . 042980 
997588 049116 


© : - 996947 055249 


TRANSFORMED DATA 


REAL IMAG 
512.499512 -.000001 
~511.081055 1.567145 
256.785889 -1.574793 
-.025975 .000161 
.099694 -.001184 
. 113036 -.001728 
. 108699 -.002016 
. 101061 -.002178 
. 093657 -.002353 
. 086534 -.002373 
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BACK TRANSFORMED DATA 


REAL 

999999 
-999961 
. 999847 
. 999661 
. 999397 
999058 
998641 
998152 
- 997588 
. 996948 


IMAG 


.900000 
006134 
.012277 
018417 
. 024560 
- 030699 
. 036837 
. 042973 
049111 
-055240 
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F01 — Matrix Operations 


(including inversion) 


Contents: 


Subroutine 
F01.G._.MM 
F01.M_INV 

F01. MM_STRASSEN 
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5.1 F01.G.MM F01 — Matrix Operations 


5.1 F01_.G_MM release 1 





1 Purpose 


F01.G.MM performs a general matrix multiply of two matrices A and B, where A is a 
P by Q matrix and B is a Q by R matrix, with P, Q and R in the range 1 to 32. 


2 Specification 


REAL MATRIX FUNCTION F01-G-MM(A ,B,P,Q,R, IFAIL) 
REAL A (, ) ? B G ) 
INTEGER P ,Q,R, IFAIL 


3 Description 


The routine is an optimised general matrix multiply using one of the following three proce- 
dures, depending on the relative sizes of P,Q and R (see [1]). 


Procedure 1 


F01.G.MM = 0.0 
DO 101=1,Q 
10 F01.G_MM = F01-G-MM + MATC(A (,1))*MATR(B (I,)) 


Procedure 2 


DO 101 =1,P 
10 F01_G_MM (I, ) = SUMR(MATC (A (I, ))*B) 





Procedure 3 
DO 10 I=1,R 
10 F01.G_MM (,I)=SUMC (A*MATR(B(,1))) 


If P/Q > 0.75 and R/Q > 0.75 procedure 1 is used, otherwise if P >= R procedure 3 is used 
or if P< R procedure 2 is used; the number 0.75 was determined empirically. 


4 References 
[1] MCKEOWN J J 


Multiplication of non-standard matrices on DAP: DAP newsletter no 7: available from the 
DAP Suppoprt Unit, Queen Mary College, Mile End Road, London E1 4NS 


5 Arguments 
A —- REAL MATRIX 


On entry A contains the first of the two matrices to be multiplied together - array 
elements outside the matrix to be multiplied must be set to zero. The contents of A are 
unchanged on exit. 


B - REAL MATRIX 


On entry B contains the second of the two matrices to be multiplied together - array 
elements outside the matrix to be multiplied must be set to zero. The contents of B are 
unchanged on exit. 
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P - INTEGER 


The number of rows in the first matrix. Unchanged on exit. 


Q - INTEGER 


The number of columns in the first matrix and the number of rows in the second matrix. 
Unchanged on exit. 


R —- INTEGER 


The number of columns in the second matrix. Unchanged on exit. 


IFAIL - INTEGER 


Unless the routine detects an error (see Error indicators below) IFAIL contains zero 
on exit. 


Error Indicators 
Errors detected by the routine: 
IFAIL = 1 3 
At least one of P, Q or R is not in the range 1 to 32. 


Auxiliary Routines 
None 


Accuracy 
You can expect six significant figures. 


Further Comments 
None 


Keywords 
Matrix multiply. 


Example 
The example given multiplies a 3 by 5 matrix of 1s by a 5 by 4 matrix of Is. 


Host program 


PROGRAM HTGMM 
INTEGER P,Q,R 
REAL A(32,32) ,B(32,32) ,C(32,32) 
COMMON /BN/P,Q,R 
COMMON /BIFAIL/IFAIL - 
COMMON /BDATA/A,B,C 
READ(5,*) P,Q,R 
CALL dapcon(’tgmm.dd’) 
CALL dapsen(’BN’,p,3) 
CALL dapent(’?TGMM?) 
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6000 
6001 
6002 


CALL daprec(’BDATA’ ,A,3*1024) 
WRITE(6,6000) IFAIL 

WRITE(6,6001) ((A(I,J),J=1,6) ,I=1,6) 
WRITE(6 , 6002) 

WRITE(6,6001) ((B(I,J),J=1,6) ,I=1,6) 
WRITE(6 , 6002) 

WRITE(6,6001) ((C(I,J),J=1,6) ,I=1,6) 
FORMAT(3X,11//) 

FORMAT(6(1X,F5.2)/) 

FORMAT(/) 

CALL DAPREL 

STOP 

END 


DAP program 


Data 


ENTRY SUBROUTINE TGMM 

REAL A(,),B(,),C(,) 

INTEGER P,Q,R 

COMMON /BN/P,Q,R 

COMMON /BIFAIL/IFAIL 

COMMON /BDATA/A,B,C 

EXTERNAL REAL MATRIX FUNCTION FO1_G_MM 
CALL CONVFSI(P,3) 

A=0.0 

B=0.0 
A(ROWS(1,P).AND.COLS(1,Q))=1.0 
BCROWS(1,Q).AND.COLS(1,R))=1.0 
c=0.0 
C=F01_G_MM(A,B,P,Q,R, IFAIL) 
CALL CONVMFE(A) 

CALL CONVMFE(B) 

CALL CONVMFE(C) 

CALL CONVSFI(IFAIL, 1) 

RETURN 

END 
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Results 

0 

1.00 1 
1.00 i 
1.00 1 
0.00 0. 
0.00 0 
0.00 0 
1.00 1 
1.00 1 
1.00 1 
1.00 1 
1.00 1 
0.00 0 
5.00 5 
5.00 5 
5.00 5. 
0.00 QO. 
0.00 0 
0.00 0 
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.00 
.00 


-00 


00 


-00 


00 


.00 
.00 
.00 
.00 
.00 


.00 


-00 


.00 


00 


00 


-00 


.00 


.00 


.00 


.00 


.00 


-00 


.00 


.00 


-00 


.00 


-00 


00 


-00 


-00 


.00 


-00 


.00 


-00 


-00 


.00 


.00 


.00 


.00 


.00 


.00 


.00 


.00 


.00 


.00 


.00 


.00 


.00 


-00 


.00 


.00 


.00 


.00 


1.00 0 
oor 0 
1.00 0 
0.00 0 
0.00 0 
0.00 0O 
0.00 0 
0.00 0 
0.00 O. 
0.00 0O 
0.00 0O 
0.00 0O 
0.00 0O 
0.00 0 
0.00 0O 
0.00 0 
0.00 0O 
0.00 0 
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.00 


.00 
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Purpose 


F01_M_INV calculates,in place, the inverse of a given N by N matrix with N in the range 1 
to 32. : 


Specification 


SUBROUTINE F01.M_INV(A , N,, IFAIL) 
REAL A(,) 
INTEGER N , IFAIL 


Description 


The matrix is inverted using Gauss-Jordan elimination with full pivoting. 


References 


None 


Arguments 
A —- REAL MATRIX 


On entry A contains the matrix to be inverted, which is assumed to be located in the 
top left of A and array elements outside the input matrix must be set to zero. On exit 
A contains the inverse of that matrix. 


N - INTEGER 


On entry N must be set to the order of the matrix to be inverted. N is unchanged on 
exit. 


IFAIL - INTEGER 
Unless the routine detects an error (see Error indicators below) IFAIL contains zero 
on exit. 

Error Indicators 

Errors detected by the routine: 
IFAIL = 1 N is not in the range 1 to 32. 


IFAIL = 2 A pivot element is equal to zero — the matrix is singular. 


Auxiliary Routines 


None 


Accuracy 


You can expect five or six significant figures for well conditioned problems. 


Further Comments 


None 
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Matrix inversion, Gauss-Jordan elimination. 


11 Example 


The example given inverts an N by N matrix, with N = 5 in this case. The matrix is 
generated as pseudo-random numbers in the range 0.0, 1.0,... , 9.0 and then the diagonal 
elements are set to the sum of the elements in each row, thus ensuring a diagonally dominant, 
and so well conditioned matrix. The inverse matrix is multiplied by the original matrix as a 
check. 


The results consist of the original matrix, the inverse matrix and their product. 


Host program 


PROGRAM HTMINV 
REAL A(32,32) ,B(32,32) ,C(32,32) 
COMMON /BN/N 
COMMON /BDATA/A,B,C 
COMMON /BIFAIL/IFAIL 
READ(5,*) N 
CALL dapcon(’tmin.dd’) 

CALL DAPSEN(’BN’,N,1) 

CALL DAPENT(?TMINV? ) 

CALL DAPREC(’BDATA’ ,A,3*1024) 

CALL DAPREC(’BIFAIL’ , IFAIL,1) 
WRITE(6,6000) IFAIL 

WRITE(6,6001) ((A(I,J),J=1,5),I=1,5) 
WRITE(6 , 6002) 

WRITE(6,6001) ((B(I,J),J=1,5),I=1,5) 
WRITE(6 , 6002) 

WRITE(6,6001) ((C(I,J),J=1,5),I=1,5) 

6000 FORMAT(2X,I2) 

6001 FORMAT(5(2X,F10.6)) 

6002 FORMAT(/) 

CALL DAPREL 
STOP 
END 


DAP progam 
ENTRY SUBROUTINE TMINV 


REAL A(,),B(,),C(,) 

INTEGER IM(,) 

COMMON /BN/N 

COMMON /BDATA/A,B,C 

COMMON /BIFAIL/IFAIL 

EXTERNAL REAL MATRIX FUNCTION GOS5MCR4 
EXTERNAL LOGICAL MATRIX FUNCTION XOSPATTERN 
EXTERNAL REAL MATRIX FUNCTION FO1GMM 

CALL CONVFSI(N, 1) 
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CALL GOSMCBEGIN 
IM=10.0*GO5MCR4(X) 

A=0.0 
A(ROWS(1,N).AND.COLS(1,N))=IM 
ACXOSPATTERN(0))=MATC(SUMC(A(,))) 
B=A 


Cc 
CALL FO1_M_INV(B,N, IFAIL) 
Cc 
C=0.0 
C=FO1_G_MM(A,B,N,N,N, IERR) 
Cc ; 
CALL CONVMFE(A) 
CALL CONVMFE(B) 
CALL CONVMFE(C) 
CALL CONVSFI(IFAIL, 1) 
RETURN 
END 
Data 
5 
Results 
0 
35.000000 8.000000 3.000000 
2.000000 21.000000 7.000000 
4.000000 1.000000 19.000000 
4.000000 6.000000 .000000 
6.000000 9.000000 1.000000 
.030777 -.007744 -.001791 
.000214 .050931 ~.018557 
-.004507 . 003413 .052401 
~.003178 -.006852 .003615 
-.004995 ~.011480 .003127 
1.000000 .000000 . 000000 
.000000 . 999999 .000000 
.000000 . 000000 .999999 
. 000000 .000000 .000000 
. 000000 .000000 .000000 
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000000 
. 000000 
- 000000 
25. 
. 000000 


000000 


007485 
.001932 
. 005672 
. 044393 
.007587 


. 000000 
. 000000 
000000 
000001 
-000000 
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.000000 
000000 
.000000 
.000000 
32. 


000000 


.004099 
004569 
005999 
011185 
. 035938 


. 000000 
-000000 
000000 
000000 
.900000 
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1 Purpose 


F01.MM_STRASSEN uses Strassen’s algorithm to multiply two (partitioned) 64 by 64 ma- 
trices. 


2 Specification 


SUBROUTINE F01.MM_STRASSEN (A , B , C) 
REAL A(,,2,2) , B(,,2,2) , C(,, 2,2) 


3 Description 


There is a well known result due to Strassen showing that 2 by 2 matrices may be multiplied 
using seven multiplications and fifteen additions instead of the eight multiplications and four 
additions required by the ‘normal’ method. This result is applied to the multiplication of 
64 by 64 matrices partitioned into 2 by 2 sub-matrices of size 32 by 32. [1]. 


4 References: 
[1] PARKINSON D 


Some interesting and useful results from complexity theory: DAP Newsletter no 2, p 8, 
August 1979: available from the DAP Support Unit, Queen Mary College, Mile End Road, 
London E1 4NS 


5 Arguments . 
© A - REAL MATRIX array of dimension (, , 2, 2) 


On exit the 64 by 64 elements of the matrix set A contain the values of the matrix 
product 


B — REAL MATRIX array of dimension (, , 2, 2) 


Before entry the elements of B must be set to the first of the 64 by 64 matrices to be 
multiplied. Unchanged on exit. 


C - REAL MATRIX array of dimension (, , 2, 2) 


Before entry the elements of C must be set to the second of the 64 by 64 matrices to 
be multiplied. Unchanged on exit. All the matrices must be partitioned into four equal 


sub-matrices. 


The matrix (, ,I,J) is occupied by the data area shown as IJ above. 
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6 Error Indicators 





None 


7 Auxiliary Routines 
This routine calls the DAP library routine Z.FO01.MM_N. 


8 Accuracy 


Depends on the data; you can normally expect six significant figures. 


9 Further Comments 


None 


10 Keywords 


Matrix multiplication, partitioned matrices, Strassen’s algorithm. 


11 Example 


Host program 


PROGRAM STRASSENTEST 


REAL A(32,32) ,B(32,32),D,E 
LOGICAL FLAG 





COMMON/TEST/A,B 
COMMON/FLAG/FLAG 


DO iJ 
DO 1 
D=I 
E=J 
A(I,J) = D¥E - 2. 
B(I,J) = (D + E)*3. 
1 CONTINUE 
CALL dapcon(’testmult.dd’) 
CALL dapsen(’TEST’ ,A,2*1024) 
CALL dapent(’?TESTMULT’ ) 
CALL daprec(’FLAG’ ,FLAG, 1) 
CALL daprel 
IF(.NOT.FLAG) GO TO 2 
WRITE(6, 100) 
100 FORMAT(20X,37HSUCCESSFUL RESULTS FROM FO1MMSTRASSEN ) 
STOP 


il 


,32 
1,32 


HoH 


2 WRITE(6, 101) 
101 FORMAT(20X,17HINCORRECT RESULTS ) 
STOP 


END 
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DAP program 





ENTRY SUBROUTINE TESTMULT 


REAL U(,,2,2),V(,,2,2),W(,,2,2),X(,,2,2) ,RELDIFF(,,2,2) 
LOGICAL FLAG 


COMMON/TEST/A(,),B(,) 
COMMON/FLAG/FLAG 


EXTERNAL REAL MATRIX FUNCTION E 


Cc 
Cc CALL CONVERSION ROUTINES 
Cc 
CALL CONVFME(A) 
CALL CONVFME(B) 
FLAG = .TRUE. 
Cc 
Cc GENERATE ENLARGED MATRIX DATA 
Cc 
v(,,1,1) =A 
w(,,1,1) =B 
v(,,1,2) = V(,,1,1) * 3.1 
w(,,1,2) = W(,,1,1) + 6.3 
V(,,2,1) = W(,,1,1) * 0.9 
W(,,2,1) = V(,,1,1) * 2.4 
© v(, ,2,2) = v(,,1,2) + 5.6 
W(,,2,2) = W(,,1,2) * 1.3 
Cc 
Cc CALL THE STRASSEN ROUTINE AND ANOTHER ROUTINE FOR 
Cc MATRIX MULTIPLICATION 
Cc 
CALL FO1_MM_STRASSEN(U,V,W) 
CALL MM2N(X,V,W) 
Cc 


c CHECK THE TWO SETS OF RESULTS CALCULATED 


DO 11 L = 1,2 
DO 11 K = 1,2 
RELDIFF(,,K,L) = E(U(,,K,L),X(,,K,L)) 
IF(ANY(RELDIFF(,,K,L).GT.0.0001))FLAG = .FALSE. 
11 CONTINUE 


Cc 
c CONVERT DATA AND RETURN TO THE HOST 
Cc 

CALL CONVSFL(FLAG, 1) 

RETURN 

END 
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REAL MATRIX FUNCTION E(X,Y) 








Cc 
C FUNCTION TO COMPARE RELATIVE VALUES OF TWO MATRICES 
Cc 

DIMENSION X(,),Y(,) 

E=x-yY 

X(ABS(X).LT.1.0E-50) = 1.0 

E(ABS(Y).GE.1.0E-50) = ABS(E/X) 

X(ABS(X - 1.0).LT.1.0E-50) = 0.0 

RETURN 

END 

SUBROUTINE MM2N(A,B,C) 
Cc 
Cc THIS SUBROUTINE IS DESIGNED TO MULTIPLY TWO 64 X 64 
Cc MATRICES TOGETHER.THE METHOD USED TO PERFORM THIS TASK 
Cc IS THE "INTUITIVE" METHOD,THAT IS , IMPLEMENTING THE 
Cc 32 X 32 MATRIX MULTIPLICATION 8 TIMES TO COMPUTE EACH 
Cc PARTITION SEPARATELY. 
Cc 

DIMENSION A(,,2,2),B(,,2,2),C(,,2,2) 

INTEGER K 
Cc 
Cc INITIALISE THE RESULTANT ARRAY. 
Cc 

A(,,1,1) = 0.0 

A(,,1,2) = 0.0 

A(,,2,1) = 0.0 

A(,,2,2) = 0.0 
Cc 
Cc PERFORM THE MATRIX MULTIPLICATION FOR EACH PARTITION 
Cc IN TURN. 
Cc 


DO 1K = 1,32 
A(,,1,1)=A(,,1,1)+MATC(B(,K,1,1))*MATR(C(K, ,1,1)) 
AC,,1,1)=A(,,1,1)+MATC(B(,K,1,2))*MATR(C(K, ,2,1)) 
AC(,,1,2)=A(,,1,2)+MATC(B(,K,1,1))*MATR(C(K, ,1,2)) 
A(,,1,2)=A(,,1,2)+MATC(B(,K,1,2))*MATR(C(K, ,2,2)) 
AC,,2,1)=A(,,2,1)+MATC(B(,K,2,1))*MATR(C(K, ,1,1)) 
A(,,2,1)=A(, ,2,1)+MATC(B(,K,2,2)) *MATR(C(K, ,2,1)) 
AC,,2,2)=A(,,2,2)+MATC(B(,K,2,1))*MATR(C(K, ,1,2)) 
A(,,2,2)=A(, ,2,2)+MATC(B(,K,2,2))*MATR(C(K, ,2,2)) 

1 CONTINUE 


RETURN 
END 


Results 





SUCCESSFUL RESULTS FROM FO1MMSTRASSEN 
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F02 — Eigenvalues and 
eigenvectors 


Contents: 


Subroutine 

F02_ ALL_EIG.VALS_TD. ES 
F02_ALL_EIG.VALS_TD.LV 
F02. EIG.VALS.TD_LV 


F02_JACOBI 
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6.1 F02.ALL.EIG.VALS_TD. ES F02 — Eigenvalues and eigenvectors 
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1 Purpose 


F02. ALL. EIG. VALS_TD_ES uses Sturm sequences to find all the eigenvalues of a symmet- 
ric tridiagonal matrix of order up to 32. 


2 Specification 


SUBROUTINE F02_.ALL_EIG. VALS_TD_ES(ALPHA , GAMMA , N , EVALS 
IC , IFAIL) 

INTEGER N , IC , IFAIL 

REAL ALPHA() , GAMMA() , EVALS() 


3 Description 


The algorithm uses the following theorem: 


Given a symmetric tridiagonal matrix with diagonal elements c,, ..., c, and off diagonal 
elements bo, ..., bn, then let the sequence q1(), ..., gn(A) be defined for any real A by: 
qi(A) =c—A 
bF 


gi(A) = (e;—A)— G9.) 


qgi-1(A) 


If a(X) is the number of negative q;(A) then this number is equal to the number of 
eigenvalues less than A. If g;_1(A) = 0 for any i, then it can be replaced in (4.2) by a 
suitably small non-zero value (see [1]). Also see [1] for an example of another use of this 
theorem. 





For each eigenvalue, an initial interval is determined which is known to contain the eigen- 
value. Each such interval is then repeatedly subdivided until further refinements produce 
no improvement in the corresponding eigenvalue or the subinterval width becomes less than 
10-7". 


4 References 
[1] BARTH W, MARTIN RS and WILKINSON J H 


Calculation of the eigenvalues of a symmetric tridiagonal matrix by the method of bisection: 
Numer Math 9, pp 386-393, 1967. 


5 Arguments 


ALPHA - REAL VECTOR 


On entry ALPHA specifies the components of the main diagonal of the tridiagonal matrix, 
that is, ALPHA (I) =A(I,I) (I=1, 2,...,N). Elements (N + 1) to 32 may be undefined; 
the argument is unchanged on exit from the sub-routine. 


GAMMA - REAL VECTOR 


On entry GAMMA specifies the components of the off diagonal of the tridiagonal matrix, 
that is, GAMMA(I) = A(I,I+ 1) = A(I+1,I) (I= 2,3,..., N). Elements not in the 
range 2 to N may be undefined; the argument is unchanged on exit from the sub-routine. 
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N - INTEGER 


On entry, N specifies the order of the tridiagonal matrix. N must lie in the range 2 to 
32, and is unchanged on exit. 


EVALS —- REAL VECTOR 


On exit, EVALS contains the N eigenvalues of the matrix in components 1 to N. 


IC —- INTEGER 


On exit, IC contains the number of calls to the Sturm sequence evaluation routine re- 
quired to isolate all the eigenvalues. Note: for each such call the Sturm sequence is 
evaluated at 1024 points simultaneously. 


IFAIL - INTEGER 


Unless the routine detects an error (see section 6) IFAIL contains zero on exit. 


Error Indicators 
Errors detected by the routine: 
IFAIL = 1 N not in the range 2 to 32 inclusive 


IFAIL = 2 After 10 calls to the Sturm sequence evaluation routine 
some eigenvalues have not converged 


Auxiliary Routines 


This routine calls the GS Ibrary routines X02. EPSILON, X05. LONG_INDEX, 
X05.SHORT_INDEX and Z. F02.STURM-_SEQ.-1. 


Accuracy 


In general, you can expect at least 6 significant figures of accuracy in the computed eigen- 
values. 


Further Comments 


None 


Keywords 


Kigenvalues, Sturm sequences, symmetric tridiagonal matrices 


Example 


The matrix used in the example is a tridiagonal matrix of the form: 


a b 
b ab 
bab 
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the eigenvalues of which are given by: 








As = a+2bcos ( — ;) C2 ae ne eee 
The largest error in the computed solution is 6 parts in 10”. 


Host program 


PROGRAM MAINES 
REAL ALPHA(32), GAMMA(32), Y(32) 
COMMON /ALPHA/ALPHA /GAMMA/GAMMA /Y/Y 
COMMON/SCALARS/N,IC, IFAIL 
N = 32 
DO 10 I = 1,32 
ALPHA (I) = 5.0 
10 GAMMA (I) = 10.0 
CALL DAPCON(’ entes.dd’) 
CALL DAPSEN(’SCALARS? ,N, 1) 
CALL DAPSEN(’ ALPHA? , ALPHA, 32) 
CALL DAPSEN(’GAMMA? , GAMMA, 32) 
CALL DAPENT(’?ENTES? ) 
CALL DAPREC(’Y? ,Y,32) 
CALL DAPREC(’?SCALARS? ,N,3) 
CALL DAPREL 
WRITE(6,100) IFAIL,IC, (Y(I), I = 1,32) 
100 FORMAT(? IFAIL =’,I5/’ IC =’,I5/ » EIGENVALUES’/(G14.7)) 





STOP 
END 


DAP program 


ENTRY SUBROUTINE ENTES 
REAL ALPHA(), GAMMA(), Y() 

COMMON /ALPHA/ALPHA /GAMMA/GAMMA /Y/Y 
COMMON /SCALARS/ N,IC,IFAIL 

CALL CONVFVE(ALPHA, 32,1) 

CALL CONVFVE(GAMMA, 32,1) 

CALL CONVFSI(N, 1) 

CALL FO2ALL_EIG_VALS_TD_ES( ALPHA ,GAMMA,N,Y,IC, IFAIL) 
CALL CONVVFE(Y, 32,1) 

CALL CONVSFI(N,3) 

RETURN 

END 
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Results 


IFAIL = 0 
Ic = 6 
EIGENVALUES 
-14.97665 
-14.90632 
-14.79012 
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6.2 F02. ALL. EIG.VALS_TD.LV F02 — Eigenvalues and eigenvectors 


6.2 FO02_ ALL_ EIG_VALS_TD_ LV release 1 





1 Purpose 


F02_ALL. EIG_VALS_TD_LV uses Sturm sequences to find all the eigenvalues of a symmetric 
tridiagonal matrix of order up to 1024. 


2 Specification 


SUBROUTINE F02_ALL.EIG_VALS_TD.LV(ALPHA , GAMMA ,N , EVALS, 
+ IC, IFAIL) 

INTEGER N , IC, IFAIL 

REAL ALPHA (,) ,GAMMA(,) , EVALS(,) 


3 Description 
The algorithm uses the following theorem: 


Given a symmetric tridiagonal matrix with diagonal elements c;, ..., c, and off diagonal 
elements bo, ..., bn, then let the sequence q:(A), ..., gn(A) be defined for any real A by: 
(A) = e-A (1) 
Q) = (6a) (852... 0) (2) 
Gi = 3 gi-1() a p iaetenyeiae: | 


If a(A) is the number of negative q;(\) then this number is equal to the number of 
eigenvalues less than . If g;-1(A) = 0 for any i, then it can be replaced in (2) by a 
suitably small non-zero value (see [1]). Also see [1] for an example of another use of this 
theorem. 





For each eigenvalue, an initial interval is determined which is known to contain the eigen- 
value. Each such interval is then repeatedly subdivided until further refinements produce 
no improvement in the corresponding eigenvalue or the subinterval width becomes less than 
10575: 


4 References 
[1] BARTH W, MARTIN RS and WILKINSON J H 


Calculation of the eigenvalues of a symmetric tridiagonal matrix by the method of bisection: 
Numer Math, 9, pp 386-393, 1967. 


5 Arguments 
ALPHA — REAL VECTOR 


On entry ALPHA specifies the components of the main diagonal of the tridiagonal matrix, 
that is, ALPHA(I) = A(I, I) (I = 1, 2, ..., N). Elements (N + 1) to 1024 may be 
undefined; the argument is unchanged on exit from the sub-routine. 


GAMMA ~ REAL VECTOR 


On entry GAMMA specifies the components of the off diagonal of the tridiagonal matrix, 
that is, GAMMA(I) = A(I,I+1)=A(I+1,I) (I= 2,3,...,.N). Elements not in the 
range 2 to N may be undefined; the argument is unchanged on exit from the sub-routine. 
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N —- INTEGER 


On entry, N specifies the order of the tridiagonal matrix. N must lie in the range 2 to 
1024, and is unchanged on exit. 


EVALS —- REAL VECTOR 


On exit, EVALS contains the N eigenvalues of the matrix in components 1 to N. 


IC - INTEGER 


On exit, IC contains the number of calls to the Sturm sequence evaluation routine re- 
quired to isolate all the eigenvalues. Note: for each such call the Sturm sequence is 
evaluated at 1024 points simultaneously. 


IFAIL - INTEGER 


Unless the routine detects an error (see section 6) IFAIL contains zero on exit. 


Error Indicators 
Errors detected by the routine: 
IFAIL = 1 N not in the range 2 to 1024 inclusive 


IFAIL = 2 After 30 calls to ther Sturm sequence evaluation routine 
some eigenvalues have not converged 


Auxiliary Routines 


This routine calls the GS library routines X02. EPSILON, X05.LONG_INDEX, 
X05_SHORT_INDEX and Z_F02.STURM_SEQ-2. 


Accuracy 


In general, you can expect about 5 or 6 significant figures of accuracy in the computed 
eigenvalues. 


Further Comments 


None 


Keywords 


Eigenvalues, Sturm sequences, symmetric tridiagonal matrices 


Example 


The matrix used in the example is a tridiagonal matrix of the form: 


a b 
bab 
bab 
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the eigenvalues of which are given by: 








st 
rs = a+-2bc0s (7) (Cao ee reer 2 


Host program 


PROGRAM MAIN 
REAL ALPHA(1024) ,GAMMA(1024) , EVALS(1024) 
COMMON /MATS/ALPHA, GAMMA, EVALS 
COMMON /SCALARS/N,IC,IFAIL 
N=128 
DO 10 I=1,128 
ALPHA(I)=5.0 
10 GAMMA(I)=10.0 
CALL DAPCON(’ ent.dd’) 
CALL DAPSEN(’?SCALARS? ,N, 1) 
CALL DAPSEN(’MATS? , ALPHA, 2*1024) 
CALL DAPENT(?ENT? ) 
CALL DAPREC(’MATS? , ALPHA, 3*1024) 
CALL DAPREC(’SCALARS? ,N,3) 
CALL DAPREL 
WRITE(6,1000) IFAIL,IC, (EVALS(I) ,I=1,128) 
1000 FORMAT(’? IFAIL =’,I5/’ IC = ’,I5/’ EIGENVALUES’/(G14.7)) 
STOP 





END 


DAP program 


ENTRY SUBROUTINE ENT 
REAL ALPHA(,) ,GAMMA(,),EVALS(,) 
COMMON /MATS/ALPHA,GAMMA,EVALS 
COMMON /SCALARS/N,IC,IFAIL 

CALL CONVFME (ALPHA) 

CALL CONVFME (GAMMA) 

CALL CONVFSI (N,1) 

CALL FO2_ALL_EIG_VALS_TD_LV (ALPHA, GAMMA,N,EVALS,IC,IFAIL) 
CALL CONVMFE (EVALS) 

CALL CONVSFI (N,3) 

RETURN 

END 
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Results 





IFAIL 0 
Ic = 20 
EIGENVALUES 
-14.99412 
-14.97626 
-14.94660 
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1 Purpose 
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F02.EIG. VALS_TD.LV uses Sturm sequences to find up to 32 selected eigenvalues of a 
symmetric tridiagonal matrix of order up to 1024. 


Specification 


SUBROUTINE F02_EIG_VALS.TD_LV(ALPHA , GAMMA ,N ,I-_EIGS, 
+ | NUM-_EIGS , EVALS, IC, IFAIL) 

INTEGER N , LEIGS() , NUM_EIGS , IC , IFAIL 

REAL ALPHA(,) , GAMMA(,) , EVALS() 


Description 


The algorithm uses the following theorem: 


Given a symmetric tridiagonal matrix with diagonal elements c,, ... c, and off diagonal 
elements bo, ... bn, then let the sequence qi(A), ... gn(A) be defined for any real A by: 


a(A)=a-rA (1) 


qi(A) = (4-a)- (ae ae n) (2) 


1(A) 


If a(A) is the number of negative g;(A) then this number is equal to the number of 
eigenvalues less than A. If g;_1(A) = 0 for any i, then it can be replaced in (4.6) by a 
suitably small non-zero value (see [1]). Also see [1] for an example of another use of this 
theorem. 


For each eigenvalue, an initial interval is determined which is known to contain the eigen- 
value. Each such interval is then repeatedly subdivided until further refinements produce 
no improvement in the corresponding eigenvalue or the subinterval width becomes less than 
10=*5:; 


References 
[1] BARTH W, MARTIN RS and WILKINSON J H 


Calculation of the eigenvalues of a symmetric tridiagonal matrix by the method of bisection. 
Numer. Math. 9 pp 386-393 (1967). 


Arguments 
ALPHA —- REAL VECTOR 


On entry ALPHA specifies the components of the main diagonal of the tridiagonal matrix, 
that is, ALPHA(I) = A(I, I) (I= 1, 2, ..., N). Elements (N + 1) to 1024 may be 
undefined; the argument is unchanged on exit from the sub-routine. 


GAMMA - REAL VECTOR 
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On entry GAMMA specifies the components of the off diagonal of the tridiagonal matrix, 

that is, GAMMA(I) = A(I,I+ 1) =A(I+1,1) (1=2,3,...,N). Elements not in the 

range 2 to N may be undefined; the argument is unchanged on exit from the sub-routine. 
N - INTEGER 


On entry, N specifies the order of the tridiagonal matrix. N must lie in the range 2 to 
0124, and is unchanged on exit. 


ILEIGS — INTEGER VECTOR 


I_EIGS is used to indicate which eigenvalues of the matrix are required. If the eigenvalues 
are [(1) <=1(2) <= ... <=1(N) then to determine the subset /(j1),/ (jo), -.-, 1 (jp) 
the first p (equals NUM -EIGS) components of 1. EIGS must be set to j1, jo, ..., jp and 
the condition 7; < jg < ... < jp must hold. Components (p+ 1) to 32 may be undefined; 
the argument is unchanged on exit. 


NUM -EIGS - INTEGER 


On entry NUM-EIGS specifies the number of eigenvalues required and must be in the 
range 1 to 32; it is unchanged on exit. 


EVALS —- REAL VECTOR 


On exit, EVALS contains the NUM_EIGS eigenvalues of the matrix in components 1 to 
NUM_EIGS. 


IC - INTEGER 


On exit, IC contains the number of calls to the Sturm sequence evaluation routine re- 
quired to isolate all the eigenvalues. Note: for each such call the Sturm sequence is . 
@ evaluated at 1024 points simultaneously. 


IFAIL - INTEGER 


Unless the routine detects an error (see section 6) IFAIL contains zero on exit. 





6 Error Indicators 
Errors detected by the routine: 
IFAIL = 1 N not in the range 2 to 1024 inclusive 


IFAIL = 2 Entries 1 to NUM_EIGS of I_EIGS are not strictly increasing 
or lie outside the range 1 to 1024 


IFAIL = 3 After 10 calls to the Sturm sequence evaluation routine 
some eigenvalues have not converged 


7 Auxiliary Routines 


This routine calls the GS library routines X02. EPSILON, X05. LONG_INDEX, 
X05.SHORT_INDEX and Z_ F02.STURM-_SEQ_2. 


8 Accuracy 


In general, you can expect about 6 significant figures of accuracy in the computed eigenvalues. 


9 Further Comments 
None 





General Support library man010.02 51 


6.3 F02_EIG.VALS.TD_LV F02 — Eigenvalues and eigenvectors 


10 


11 


52 


Keywords 


Eigenvalues, Sturm sequences, symmetric tridiagonal matrices 


Example 


The matrix used in the example is a tridiagonal matrix of the form: 


a b 
bab 
bab 


the eigenvalues of which are given by: 





A = a42bc0s (—*Z_) (s=1, 2,...,n) 


The eigenvalues requested are spread throughout the spectrum and the largest error in the 
computed solution was 7 parts 10’. 


Host program 


PROGRAM MAIN 

REAL ALPHA(1024), GAMMA(1024) , Y(32) 
INTEGER IEIGS(32) 

COMMON /MATS/ALPHA,GAMMA 

COMMON /IEIGS/IEIGS /Y/Y 

COMMON /SCALS/N,NUMEIGS,IC,IFAIL 

N = 1024 

DO 10 I = 1,1024 

ALPHA(I) = 5.0 


10 GAMMA (I) = 10.0 
NUMEIGS = 32 
DO 20 I = 1,32 


20 IEIGS(I) = 32#I 

CALL DAPCON(? ent.dd) 

CALL DAPSEN(’MATS?’ , ALPHA, 2*1024) 

CALL DAPSEN(’IEIGS’ , IEIGS, 32) 

CALL DAPSEN(’SCALS’ ,N,2) 

CALL DAPENT(’ENT? ) 

CALL DAPREC(’SCALS? ,N,4) 

CALL DAPREC(’Y’ ,Y,32) 

CALL DAPREL 

WRITE(6,100) IFAIL,IC, (IEIGS(I),Y(I), I= 1,32) 
100 FORMAT(’ IFAIL =’,I5/’? IC =’,15/ 

* EIGENVALUES’ /(1I5,5X,G14.7)) 
STOP 
END 
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DAP program 





ENTRY SUBROUTINE ENT 
INTEGER IEIGS() 

REAL ALPHA(,), GAMMA(,), Y() 

COMMON /MATS/ALPHA, GAMMA 

COMMON /IEIGS/IEIGS /Y/Y 

COMMON /SCALS/N, NUMEIGS,IC,IFAIL 

CALL CONVFME(ALPHA) 

CALL CONVFME(GAMMA) 

CALL CONVFVI(IEIGS ,32,1) 

CALL CONVFSI(N,2) 

CALL FO2_EIG_VALS_TD_LV(ALPHA,GAMMA,N, IEIGS,NUMEIGS,Y,IC,IFAIL) 
CALL CONVVFE(Y, 32,1) 

CALL CONVSFI(N,4) 


RETURN 
END 
Results 
IFAIL = 0 
Ic = 6 
EIGENVALUES 
, 32 ~14.90388 
co 64 -14.61645 
96 -14.14048 
128 -13.48052 
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6.4 FO02_ JACOBI release 1 





1 Purpose 


F02. JACOBI calculates the eigenvalues and eigenvectors of a real symmetric matrix of order 
32 x 32. 


The method is based on the classical Jacobi algorithm using plane rotations. 


2 Specification 


SUBROUTINE F02_JACOBI(C , EVALUES , Q , BOOL) 
REAL C(,) , EVALUES() , Q(,) 
LOGICAL BOOL 


3 Description 


The cyclic Jacobi method is a well known technique for determining the eigensolution of a 
matrix [4]. A real symmetric matrix A is reduced to diagonal form by application of plane 
rotations. Full details can be found in [2]. 


4 References 


[1] MODIJ J 


Error analysis for the parallel Jacobi method: QMC internal report, Department of Com- 
puter Science and Statistics, Queen Mary College, Mile End Road, London, E1 4NS: available 
on request from the DAP Suppost Unit at Queen Mary College. 


MODI J J © 


Jacobi methods for eigenvalue and related problems in a parallel computing environment: 
Ph D thesis, University of London. 





[2 


—= 


[3] SAMEH A H 


On Jacobi and Jacobi-like algorithms for the parallel computer: Mathematics of Computa- 
tion, v 25, no 115, pp 579-590, July 1971. 


— 


[4] WILKINSON J H 
The Algebraic Eigenvalue Problem: Clarendon Press, Oxford, 1965. 


5 Arguments 
C —- REAL MATRIX 


On entry C contains the real symmetric matrix whose eigenvalues are required, and is 
unchanged on exit. 


EVALUES - REAL VECTOR 


On exit EVALUES will contain the eigenvalues of C, in ascending order. 


Q - REAL MATRIX 


If BOOL was set to .TRUE. on entry then on exit the columns of Q will contain the 
eigenvectors of C. 


The eigenvector in column I corresponds to the I** element of EVALUES. 
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BOOL - LOGICAL 


If BOOL is set to .TRUE. on entry, the eigenvectors of C will be calculated as well as 
the eigenvalues; BOOL is unchanged on exit. 


Error Indicators 


None 


Auxiliary Routines 


This routine calls the GS Ibrary routines M01. PERMUTE_COLS, M01_SORT_V_R4 
and X05_ PATTERN. 


Accuracy 


The method is numerically very stable (see [1]). Tests show that the routine agrees with 
EISPACK routines, run on a 60 bit word computer, to 4 or 5 significant figures. 


Further Comments 


None 


Keywords 
Disjoint Rotations, Jacobi Method, Parallel Algorithm. 


Example 


The example finds the eigensolution of a 32 x 32 matrix. 


Host program 


PROGRAM MAINJACOBI 

LOGICAL BOOL 

COMMON /A/A(32,32) /EV/EIGENVALUES (32) 

COMMON /Q/Q(32,32) /BOOL/BOOL 

BOOL = .TRUE. 

DO 20 J = 1,32 

DO 20 I = 1,32 

A(I,J) = 0.0 

IF ((I + 1).EQ.J) ACI,J) 

IF ((J + 1).EQ.1) A(I,J) 
20 CONTINUE 

CALL DAPCON(’v3.dd’) 

CALL DAPSEN(?A?’,a,1024) 

CALL DAPSEN(’BOOL? , BOOL, 1) 

CALL DAPENT(?’V3?) 

CALL DAPREC(’EV’ , eigenvalues , 32) 

WRITE (6,1000) (EIGENVALUES(I),I = 1,32) 


“ow 
ee ee 
oo 
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1000 


FORMAT (’? Eigenvalues ’ /(1X,F14.5)) 


WRITE (6,1500) 


1500 


FORMAT(’? Eigenvectors’) 
CALL DAPREC(’Q’ ,Q,1024) 
CALL DAPREL 

J=1 


DO 40 I = 1,32 


40 
2000 


WRITE (6,2000) Q(I,J) 
FORMAT(1X,F14.5) 

STOP 

END 


DAP program 


Results 


Eigenval 


-1. 
tL. 
-1. 
-1. 
-1. 
-1. 
-1i. 


-1 


-1. 
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ENTRY SUBROUTINE V3 
REAL A(,) , Q(,) ,EIGENVALUES() 
LOGICAL BOOL 

COMMON /A/A /EV/EIGENVALUES 
COMMON /Q/Q /BOOL/BOOL 

CALL CONVFME(A) 


CALL CONVFSL(BOOL, 1) 

CALL FO2_JACOBI(A, EIGENVALUES ,Q,BOOL) 
CALL ‘CONVVFE (EIGENVALUES, 32, 1) 

CALL CONVMFE(Q) 

RETURN 

END 


ues 

99084 
96374 
91889 
85665 
TTT58 
68242 
57204 
. 44740 
30967 
. 16006 
-99995 
. 83079 
-65410 
- 47150 
- 28462 
-09516 
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-09516 
» 28462 
-47150 
- 65410 
- 83079 
. 99995 
. 16006 
. 30967 
-44740 
. 57204 
- 68242 
- TTT58 
- 85665 
. 91889 
- 96374 
1.99084 
Eigenvectors 

-.02315 

-04610 

-. 06866 

- 09063 

-.11182 

. 13204 

-.15109 

. 16879 

-.18499 

© - 19953 
-.21228 

«22313 

~.23198 

- 23876 

- . 24338 

. 24582 

~. 24603 

- 24401 

~.23977 

23334 

~. 22477 

-21414 

~-.20154 

. 18710 

~.17093 

. 15319 

~.13404 

- 11365 

-.09221 

- 06992 

~.04697 

. 02360 





Ca a 
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7.1 F04_BIGSOLVE F04 — Simultaneous linear equations 


7.1 F04_BIGSOLVE release 1 





1 Purpose 


F04 _ BIGSOLVE is a routine for solving large sets of linear equations. The maximum size of 
the system depends on the size of the DAP store — for a 32 by 32 DAP with a 4 Mbyte store 
this maximum size is 1023, whereas for a 32 by 32 DAP with an 8 Mbyte store the maximum 
size is 1407. The method used was developed by D Hunt; it consists of a block form of Gauss 
Elimination with column pivoting. The matrix of the coefficients of the equations is of size 
‘SIZE’ by ‘SIZE’ and the right hand side is assumed to be held in column ‘SIZE’ + 1. The 
whole matrix is held in the DAP partitioned in DAPSIZE blocks. 


You are not recommended to use this routine for systems of order 32 or less — for which you 
should use the routine F04_GJ_NLE_ES. 


2 Specification 


SUBROUTINE F04.BIGSOLVE(BIGM , SIZE , ALLBLKS , IFAIL) 
REAL BIGM (,, ALLBLKS, ALLBLKS) 
INTEGER SIZE , IFAIL , ALLBLKS 


3 Description 


You can use this routine to solve a system of equations of maximum size N = 1023 on the 
4 Mbyte 32 by 32 DAP, (N = 1407 on the 8 Mbyte 32 by 32 DAP) using a block form of Gauss 
elimination with column pivoting [2]. After the forward step, the matrix is conceptually of 





the form: (illustrated for a hypothetical 4 by 4 DAP and for N = 11) © 
1000 XX X X X XXX 
0100 XXX X XXX X 
0010 X XXX X XXX 
0001 XX XX XXX X 
0000 1000 Xx XXX 
0000 0100 XXX X 
0000 0010 X KX X 
0000 0001 XXX X 
0000 0000 100 X 
0000 0000 010X 
0000 0000 001Xx 
0000 0000 0000 


( X = non zero value) 


Gauss Jordan elimination is used for the diagonal blocks (see [1]). In practice, the diagonal 
and below diagonal blocks are not needed and are therefore left undefined. 


On DAP the relevant part of the pivot column will in general be spread over several sheets. 
In DAP 500 that part of the pivot column is extracted in order to find the maximum in a 
single operation. 
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The factors by which the rows of the large matrix are multiplied are obtained by dividing 
the pivot column by the pivot element. This is done in a single matrix division operation on 
the extracted data. 





The solution time is ultimately O(m? x d), where the matrix is partitioned into m by m 
sheets each of size d by d to match the DAP 500 array. (In terms of the parameters below, 
N =SIZE, ((m—1)d < N < md) and m=ALLBLKS ). 


4 References 


[1] FOX, L 
Numerical Linear Algebra: Chapters 3, 7, Oxford University Press, Oxford,1964 


HUNT, DJ 

[2] Solution of a large system of equations on DAP using a hybrid Gauss/Gauss Jordan 
method: DAPSU Technical Report 7.27: available on request from The DAP Support 
Unit, Queen Mary Collge, Mile End Road, London El 4NS 

[3] PARKINSON, D and LIDDELL, H M 


The measurement of performance on a highly parallel system: IEEE Trans on Com- 
puters, Special Issue, Nov 1982 


5 Arguments 


BIGM -— REAL MATRIX array of dimension ( , ,AALLBLKS,ALLBLKS) 


On entry the first SIZE rows and columns must be set to the elements of the matrix of 

© coefficients of the’ equations defining the linear system. The right-handside of the equa- 
tions is stored in column SIZE + 1. The values in BIGM are changed during execution 
of the subroutine, and on exit column SIZE + 1 contains the solution of the system. 


SIZE —- INTEGER 


On entry SIZE must be set to the order of the system. Unchanged on exit. SIZE must 
not be less than 2. 


ALLBLKS - INTEGER 
On entry ALLBLKS must be set to the number of DAP partitions needed to store the 
complete system (i.e. including the RHS). Unchanged on exit. 

IFAIL —- INTEGER 


Unless the routine detects an error (see Error Indicators below) IFAIL contains zero 
on exit. 


6 Error Indicators 
Errors detected by the routine: 
IFAIL = 1 SIZE is less than 2 
IFAIL = 2 One of the conditions: 


32*(ALLBLKS - 1) < SIZE 
32*ALLBLKS - 1 >= SIZE 


has been violated 
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Error Indicators - continued 


F04 — Simultaneous linear equations 


IFAIL = 3 A zero pivot has been found during the back substitution process. 


The calculation is terminated 


IFAIL = 4 A very small pivot has been found during the back substitution 


process and the matrix is probably singular. 


Computation proceeds anyway, but the results should be treated 


with caution 


Auxiliary Routines 
None 


Accuracy 


The accuracy depends on the conditioning of the system; during extensive testing of this 
single precision implementation of the routine the maximum residual was approximately 


10>; 


Further Comments 
None 


Keywords 


Gauss elimination, Gauss-Jordan, linear solver. 


Example 


Host program 


PROGRAM HOSTBIGSOLVER 
COMMON/INPUT1/A(32,32,5,5) 
COMMON/STATS/FNMONE , FNMTWO , FNMINF 
COMMON/IFAIL/IFAIL 


DATA N,IX/32,1111111/ 


CALL DAPCON(’bigtest.dd’) 
CALL INITDATA(N ,IX) 
CALL DAPSEN(?INPUT1? ,A,25*1024) 
CALL DAPENT(’BIGSOLVETEST’ ) 
CALL DAPREC(?IFAIL’ , IFAIL, 1) 
CALL DAPREC(’STATS’ , FNMONE, 3) 
CALL DAPREL 
WRITE(6 ,99) IFAIL 

99  FORMAT(10X,7HIFAIL =,I3) 
IF(IFAIL.EQ.1.OR.IFAIL.EQ.2.0R.IFAIL.EQ.3)STOP 
WRITE(6, 100) FNMONE, FNMTWO, FNMINF 
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100 FORMAT(20H SUM OF RESIDUALS = ,E10.4// 
131H SUM OF SQUARES OF RESIDUALS = ,E10.4// 
220H MAXIMUM RESIDUAL = ,E10.4) 
STOP 
END 





DAP program 


SUBROUTINE INITDATA(N,IX) 
COMMON/INPUT1/A(32,32,5,5) 


c 
c THIS SUBROUTINE CREATES THE INITIAL SEEDS THAT THE DAP CAN USE TO 
Cc CALCULATE EXACTLY THE REQUIRED SET OF PSEUDO-RANDOM NUMBERS. 
Cc THIS IS DONE IN ORDER TO BE ABLE TO MAKE FAIR COMPARISONS IN 
c RESPECT OF RUNTIME AS WELL AS NUMERICAL RESULTS 
c 
DO iL=1,5 
DO 1k =1,5 
dbo 1J=41,N 
DO11I=1,N 


IY =FLOAT(IX)/22369.624 
IX=125*IX-2796203+1LY 
ACI,J,K,L) = FLOAT(IX)/2796203. 
1 CONTINUE 
©) RETURN 


END 


ENTRY SUBROUTINE BIGSOLVETEST 
COMMON/INPUT1/A(, ,5,5) 
COMMON/STATS/FNMONE , FNMTWO , FNMINF 
COMMON/IFAIL/IFAIL 


REAL BIGM(,,5,5),QSAVE(,5),TRHS(,5),RESIDU(,5) ,MAXIMUM(,5) 
REAL MULT(,),X(,5) 
INTEGER N, IFAIL, DAPSIZE,RHSCOL 


NDAPS = 5 
DO 700 L = 1,NDAPS 
DO 700 K = 1,NDAPS 
CALL CONVFME (AC , ,K,L)) 
700 CONTINUE 
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400 


500 


200 


300 


70 


90 
80 


60 
600 
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DAPSIZE = 32 
N = 150 
RHSCOL = N — (NDAPS - 1)*DAPSIZE + 1 
DO 400 L = 1,NDAPS 
DO 400 K = 1,NDAPS 

BIGM( , ,K,L) = AC , ,K,L) 


CONTINUE 

DO 500 L = 1,NDAPS 

QSAVE( ,L) = AC ,RHSCOL,L,NDAPS) 
CONTINUE 


CALL F04_BIGSOLVE(BIGM,N,NDAPS, IFAIL) 
IF(IFAIL.EQ.0.OR.IFAIL.EQ.4)GO TO 200 
CALL CONVSFI(IFAIL, 1) 

RETURN 


CONTINUE 

DO 300 K = 1,NDAPS 

X( ,K) = BIGM( ,RHSCOL,K,NDAPS) 
CONTINUE 


FNMONE = O. 

FNMTWO = 0. 

FNMINF = 0. 

DO 60 K = 1,NDAPS 

TRHS( ,K) = 0. 
= 1,N 


DO 70 L DAPS 
MULT = MATR( XC ,L)) 
TRHS( ,K) = TRHS( ,K) + SUMC(MULT*A(, ,K,L)) 
CONTINUE 
RESIDU( ,K) = ABS(TRHS( ,K) - QSAVE( ,K)) 
IF(K .NE. NDAPS) GO TO 80 
DO 90 I = RHSCOL,DAPSIZE 
RESIDU(I,NDAPS) = 0.0 
QSAVE(I,NDAPS) = 0.0 
TRHS(I,NDAPS) = 0.0 
CONTINUE 
CONTINUE 
FNMONE = FNMONE + SUM(RESIDU( ,K)) 
FNMTWO = FNMTWO + SUM( RESIDU( ,K)#*#*2) 
MAXIMUM( ,K) = 0. 
MAXIMUM(RESIDU( ,K) .GT.MAXIMUM( ,K) ,K) 
IF (MAXV(MAXIMUM( ,K)).GT.FNMINF) FNMINF 
CONTINUE 
CONTINUE 
CALL CONVSFE(FNMONE, 3) 
CALL CONVSFI(IFAIL, 1) 
RETURN 
END 


RESIDU( ,K) 
MAXV(MAXIMUM( ,K)) 
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Results 





IFAIL = 
SUM OF RESIDUALS = 0.9086E-01 
SUM OF SQUARES OF RESIDUALS = 0.7045E-06 
MAXIMUM RESIDUAL = 0.1943E-03 


0 
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rae F04 _GJ_NLE _ES release 1 


1 Purpose 


F04 .GJ_NLE_ES is a routine for solving the system of linear equations Az = b for z, where 
A is a non sparse matrix of order N in the range 1 to 32, using the Gauss Jordan method. 
It is not particularly efficient for small values of N. 


2 Specification 


SUBROUTINE F04_GJ_NLE_ES(A ,X ,Q,N, IFAIL) 
REAL A(,),X(), Q() 
INTEGER N , IFAIL 


3 Description 


The Gauss Jordan method [1,2] can be considered as a variant of Gauss elimination, but the 
elimination is also applied to terms above the diagonal at each stage. 


For example, for a 4 by 4 system: 


Step 0 am Gao Se Gane 
XX XX = X 
XXXXK = X 
XXXX = X 
Step 1 XXXX = X 
OxXXxX = X 
Ox xX = X 
OXXX = X 
(This is the same as in Gauss elimination) 
Step 2 XOXXK =X 
Ox XxX = X 
ooxxXx = X 
OooxxX = X 
Step 3 XOooxX = X 
OoxOxX = X 
OoOoOxxX = X 
OooxxXx = X 
Step 4 X¥000 = X 
ox00o0 = X 
0oo0oxo0 = X 
oo0o0oxXK = X 


(X represents a non zero value) 
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Thus the parallelism at each step is maximised and there is no need to perform the back 
substitution. On a computer with mz™m parallel processors, where m exceeds the number 
of equations, N, the operation count for Gauss Jordan is N divisions, multiplications and 
subtractions, which is the same number of operations required by the elimination phase of 
Gauss elimination. However, the latter also requires N —1 multiplies and subtractions for the 
back substitution phase. On a serial machine, the operation count for Gauss Jordan is O (2), 





which is greater than that for Gauss elimination - O (A). The back substitution phase takes 
O(N?) operations and is therefore negligible for large systems. , 


4 References 


[1] FLANDERS P M , HUNT D J, REDDAWAY S F and PARKINSON D 
Efficient high speed computing with the distributed array processor, in High Speed Com- 
puter and Algorithm Organisation: Academic Press, London, 1977 


[2] WEBB S J 


Solution of elliptic partial differential equations on the ICL Distributed Array Processor: 
ICL Technical Journal, vol 2, 175 — 189 (1980) 


5 Arguments 
A - REAL MATRIX 


On entry, elements A; ;) (7, 7 =1,...,.N) must be set to the elements of the matrix 
defining the linear system. The argument is unchanged on exit. 


© X - REAL VECTOR 


On exit the first N elements of X will contain the solution of the system. 


Q - REAL VECTOR 


On entry, the first N elements of Q should contain the values of the right hand side (b) 
of the system. The argument is unchanged on exit. 


N - INTEGER 


On entry, N must be set to the order of the system; it is unchanged on exit. 


IFAIL - INTEGER 


Unless the routine detects an error (see Error Indicators below) IFAIL contains zero 
on exit. 


6 Error Indicators 
Errors detected by the routine: 


IFAIL = 1 N is not in the range 1 to 32. 
IFAIL = 2 A zero pivot has been found. The calculation is terminated. 
IFAIL = 3 A very small pivot has been found and the matrix is probably 


singular. Computation proceeds anyway, but the results should 
be treated with caution. 


7 Auxiliary Routines 


None 
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8 Accuracy 


Accuracy depends on the conditioning of the system; during testing of this single precision 
implementation, the maximum residual was less than 107°. 


9 Further Comments 


None 


10 Keywords 


Gauss Jordan, linear system solver 


11 Example 


Host program 


.PROGRAM HOSTSOLVER 
COMMON/INPUTD1/A(32,32) 
COMMON/INPUTD2/Q(32) ,X(32) 
COMMON/STATS/FNMONE , FNMTWO , FNMINF 
COMMON /IFAIL/IFAIL 


DATA N,IX/32,1111111/ 


CALL INITDATA(N,IX) 
CALL DAPCON(’gjtest -dd’) 
CALL DAPSEN(*INPUTDATA1? ,a, 1024) 
CALL DAPSEN(?’ INPUTDATA2’ ,Q,32) 
CALL DAPENT(’GJTEST? ) 
CALL DAPREC(?IFAIL’ , IFAIL, 1) 
CALL DAPSEN(?’ INPUTDATA2? ,x, 32) 
WRITE(6 , 200) IFAIL 
200 FORMAT(10X,8H IFAIL =,12) 
IF(IFAIL.NE.0)STOP 
CALL DAPREC(’STATS’ , FNMONE, 3) 
CALL DAPREL 
WRITE(6, 100) FNMONE, FNMTWO, FNMINF 
100 FORMAT(20H SUM OF RESIDUALS = ,E10.4// 
131H SUM OF SQUARES OF RESIDUALS = ,£10.4// 
220H MAXIMUM RESIDUAL = ,E10.4) 
STOP 
END 


SUBROUTINE INITDATA(N,IX) 


COMMON/INPUTD1/A(32,32) 
COMMON/INPUTD2/Q(32) ,X(32) 
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aaaaana 


THIS SUBROUTINE CREATES THE INITIAL SEEDS THAT THE DAP CAN USE 
TO CALCULATE EXACTLY THE REQUIRED SET OF PSEUDO-RANDOM NUMBERS. 
THIS IS DONE IN ORDER TO BE ABLE TO MAKE FAIR COMPARISONS IN 
RESPECT OF RUNTIME AS WELL AS NUMERICAL RESULTS 


po iI =1,N 
pO iJ=1,N 
IY =FLOAT(IX) /22369.624 
IX=125*IX-2796203*1Y 
ACI,J) = FLOAT(IX) /2796203 
CONTINUE 
pO 2 I = 1,N 
IY = FLOAT(IX)/22369.624 
IX=125*IX-2796203*1Y 
Q(I) = FLOAT(IX)/2796203 
CONTINUE 
RETURN 
END 


DAP program 


+ 


ENTRY SUBROUTINE. GJTEST 
COMMON/INPUTDATA1/A(, ) 
COMMON/INPUTDATA2/Q() ,X() 
COMMON/STATS/FNMONE , FNMTWO , FNMINF 
COMMON/IFAIL/IFAIL 


REAL ASAVE(,) ,QSAVE() , TRHS() ,RESIDU() ,MAXIMUM() , MULT(,) 
,QSAVE1() 
LOGICAL MASK(,) , VMASK() 


CALL CONVFME(A) 

CALL CONVFVE(Q,32,1) 
ASAVE = A 

QSAVE = Q 

QSAVE1 = QSAVE 


N = 27 

MASK = ROWS(1,N).AND.COLS(1,N) 
VMASK = ELS(1,N) 

QSAVE = QSAVE1 

QC(VMASK) = QSAVE 
Q(.NOT.VMASK) = 0. 

A(MASK) = ASAVE 

A(.NOT.MASK) = 0. 
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CALL F04_GJ_NLE_ES(A,X,Q,N,IFAIL) 
X(.NOT.VMASK) = 0. 
QSAVE(.NOT.VMASK) = 0. 
IF(IFAIL.NE.0)GO TO 100 

TRHS =0. 

MULT=MATR(X) 

TRHS = SUMC(MULT*ASAVE) 
TRHS(.NOT.VMASK) = 0. 

RESIDU = ABS(TRHS - QSAVE) 
FNMONE=SUM(RESIDU) 

FNMTWO= SUM(RESIDU**2) 

MAXIMUM = 0. 
MAXIMUM(RESIDU.GT.MAXIMUM) = RESIDU 
FNMINF = MAXV(MAXIMUM) 


CALL CONVVFE(X, 32,1) 

CALL CONVSFE(FNMONE, 3) 
100 CONTINUE 

CALL CONVSFI(IFAIL, 1) 


RETURN 
END 


Results 


IFAIL = 0 
SUM OF RESIDUALS = 0.3069 


SUM OF SQUARES OF RESIDUALS = 0.3604E-06 


MAXIMUM RESIDUAL = 0.1466E-03 
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7.3 F04_QR_GIVENS_SOLVE release 1 





1 Purpose 


F04.QR_GIVENS_SOLVE solves the linear system Ar = 6) for x, where A is an n by n 
matrix with 2 < n < 33. The routine may be used to solve simultaneously for up to 32 
different right hand side vectors b. 


2 Specification 


SUBROUTINE F04.QR_GIVENS_SOLVE(A ,X ,B,N , NB, IFAIL) 
INTEGER N , NB, IFAIL 
REAL A(,) , X(,) , B(,) 


3 Description 


The routine factorizes the given n by n matrix A as: 
QA=R 


where Q is an orthogonal matrix and r is upper triangular. 


Givens method of plane rotations is used to annihilate elements of A below the leading 

diagonal until the matrix R remains. This leaves an upper triangular system which is solved 

by back substitution. Row i of A is used to annihilate the element in position (i + 1,j) by 
@ pre-multiplying A by a matrix-of the form: 


Pie = diag (Ii-1), UGi41)) n-i-1)) 31 <j < n-1 


where Uj; 41) = ( ea 


. 2 2 
eae i ) , with e>+s7=1 


In the usual serial application, these rotations are applied sequentially, but on the DAP you 
can perform up to } rotations simultaneously [1]. 


4 References 
[1] SAMEH A H and KUCK DJ 


On stable parallel linear system solvers: Journal of the Association of Computing 
Machinery, vol 25, no 1, pp 81-91. 


5 Arguments 


A — REAL MATRIX 


On entry, elements Ay; ;) (= 1, 2,..., N; 7 = 1,2, ..., N) must be set to the elements 
of the matrix defining the linear system. A is unchanged on exit. 


X — REAL MATRIX 


On exit, column 7 of X will contain the solution of the system corresponding to the i** 
column of B. 
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Arguments - continued 


B —- REAL MATRIX 


On entry, columns 1 to NB must give the NB right hand side vectors. B is unchanged 
on exit. 


N ~ INTEGER 


On entry, N must be set to the order of the matrix A. N is unchanged on exit. 


NB - INTEGER 


On entry, NB must be set to the number of right hand side vectors for which the system 
is to be solved. NB is unchanged on exit. 


IFAIL —- INTEGER 


Unless the routine detects an error (see Error Indicators below) IFAIL contains zero 
on exit. 


Error Indicators 
Errors detected by the routine: 


IFAIL = 1 N is not in the range 3 to 32 or NB is not in the range 1 to 32 


IFAIL = 2 A zero pivot has been found during the back substitution process, 
that is, the matrix is singular 


IFAIL = 3 A very small pivot has been found during the back substitution 
process and the matrix is probably singular. Computation proceeds 
anyway, but you should treat the results with caution 


Auxiliary Routines 
This routine calls the DAP library routines Z.F04. BACK_SUBST, 


Z.FO4_SPREAD_LMAT_EAST, Z.FO4.SPREAD_RMAT_EAST and Z_FO4. UPDATE. 
Accuracy 


Empirical results indicate that errors may be expected in the eth op 7th significant digit. 
The routine will return IFAIL = 3 (see Error Indicators above) if the condition: 


MA tJ | Fei; | > 5x10° 
MIN; |Rii| 
is satisfied, where R;; is the upper triangular matrix defined in Description above. 


Further Comments 


You must not use common blocks with the names: 
C_F04_QR1 and C.F04_QR2 


Keywords 


Givens’ rotation, linear equations 
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11 Example 


The example solves a 5 by 5 linear system with one right hand side. The true solution vector 
isfG tala. 


Host program 


1000 


2000 


PROGRAM MAINGIVEN 
REAL A(32,32) ,X(32,32) ,B(32,32) 
COMMON /MATS/A,X,B 

COMMON /SCALARS/ N,NB,IFAIL 

READ(5,*) N,NB 

READ(5,*) ((A(I,J),J=1,N), I=1,N) 
READ(5,*) ((BC(I,J),J=1,NB),I=1,N) 
CALL DAPCON(’ entgiven.dd’) 

CALL DAPSEN(’SCALARS?’ ,N,3) 

CALL DAPSEN(?MATS? ,A,3*1024) 

CALL DAPENT(’? ENTGIVEN? ) 

CALL DAPREC(’SCALARS’ ,N,3) 

CALL DAPREC(?MATS’ ,A,2*1024) 

CALL DAPREL 

WRITE (6,1000) IFAIL 

FORMAT( ’ IFAIL = ’,I5) 

IF (IFAIL.NE.O .AND. IFAIL.NE.3) STOP 
WRITE(6,2000) ((X(I,J),J=1,NB),I=1,N) 
FORMAT(/’ Solution: ’/(1X,F12.7)) 

STOP 

END 


DAP program 


ENTRY SUBROUTINE ENTGIVEN 
REAL A(,),X(,),B(,) 

COMMON /MATS/A,X,B 

COMMON /SCALARS/N,NB,IFAIL 
CALL CONVFME(A) 

CALL CONVFME(B) 

CALL CONVFSI(N,3) 

CALL F04_QR_GIVENS_SOLVE(A,X,B,N,NB,IFAIL) 
CALL CONVMFE(X) 

CALL CONVSFI(N,3) 

RETURN 

END 
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Data 
5 i 
3.0 -7.0 1.5 2.5 6.1 
8.0 1.6 0.0 -3.0 2.8 
-0.5 1.6 2.3 7.4 -8.5 
0.0 -1.0 -2.3 1.7 5.8 
2.7 1.3 -3.5 0.0 4.1 
6.1 9.4 2.3 4.2 4.6 
Results 
IFAIL = 0 
Solution: 
0.9999998 
0.9999985 
0.9999961 
0.9999998 
0.9999990 
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7.4 F04_TRIDS_ES release 1 





1 Purpose 


F04.TRIDS_ES returns the solution of a tridiagonal linear system of equations of order up 
to 32. That is, it finds vector x where: 


Mr=y 


and M is a tridiagonal matrix. 


2 Specification 


REAL VECTOR FUNCTION F04-TRIDS_ES(A ,B,C,Y,N , IFAIL) 
INTEGER N , IFAIL 
REAL A(),B(),C(), YO 


3 Description 


The algorithm used is of the recursive doubling type. At each step the distance of the outer 
diagonals from the main diagonal is doubled. When only a diagonal matrix remains the 
solution is obtained by a simple division. Full details may be found in [1]. 


4 References 
{1] WHITEWAY J 


A parallel algorithm for solving tridiagonal systems: DAPSU Newsletter, 3 December 
© 1979: available on request from the DAP Support Unit, Queen Mary College, Mile 
End Road, London E1 4NS 


5 Arguments 
A - REAL VECTOR 


On entry, elements 2 to N of A must be set to the values of the lower diagonal of the 
tridiagonal matrix. That is, if the matrix is M = m(i,j) then A(J) must be set to 
M(U,I-—1) (I = 2,...,.N). Elements with subscripts not in the range 2 to N are 
ignored. A is unchanged on exit. 


B - REAL VECTOR 


On entry, elements 1 to N of B must be set to the values of the main diagonal of the 
tridiagonal matrix. That is, if the matrix is M = m(i,j) then B(J) must be set to 
M(,1I) (I=1,..., N). Elements with subscripts not in the range 1 to N are ignored. 
B is unchanged on exit. 


C - REAL VECTOR 


On entry, elements 1 to N — 1 of C must be set to the values of the upper diagonal of 
the tridiagonal matrix. That is, if the matrix is M = m(i,j) then C(I) must be set to 
M(U,I+1) (I =1,...,N—1). Elements with subscripts. not in the range 1 to N —1 
are ignored. C is unchanged on exit. 


Y - REAL VECTOR 


On entry, elements 1 to N of Y must be set to the values of the RHS vector. Elements 
with subscripts not in the range 1 to N are ignored. Y is unchanged on exit. 





General Support library man010.02 75 











7.4 F04_TRIDS_ES F0-+4 — Simultaneous linear equations 


10 


11 


76 


Arguments - continued 


N - INTEGER 
On entry, N must specify the size of the system (in the range 2 to 32). That is, for 
Mz = y, M must be N by N. 

IFAIL - INTEGER 


Unless the routine detects an error (see Error Indicators below) IFAIL contains zero 
on exit. 


Error Indicators 
Errors detected by the routine: 


IFAIL = 1 At some stage during the calculation, an element on the leading 
diagonal is zero. This implies the original matrix was singular. The 
contents of F04._ TRIDS_ES in this case are undefined 


IFAIL = 2 At some stage during the calculation, the matrix has ceased to be 
diagonally dominant. Note: this is only a warning and the routine 
continues to completion (if possible) 


IFAIL = 3 N is not in the range 2 to 32 


Auxiliary Routines 


None 


Accuracy 


General results seem to indicate that the more diagonally dominant the system is the more 
accurate the results. IFAIL = 1 is possible for non-diagonally dominant systems even if the 
system is non-singular. 


Further Comments 


None 


Keywords 


Tridiagonal linear systems 


Example 


The example given is such that the solution vector should be 1. The system is diagonally 
dominant. 


Host program 


PROGRAM MAINTRIDSES 
REAL ANS(32) 

COMMON /ANS/ANS/IFAIL/IFAIL 
CALL DAPCON(’tridses.dd’) 
CALL DAPENT(’ENTTRIDSES’ ) 
CALL DAPREC(’ ANS? , ANS, 32) 
CALL DAPREC(?IFAIL’ , IFAIL,1) 
CALL DAPREL 

WRITE (6,1000) IFAIL 
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1000 FORMAT(’ IFAIL =’,I5) 


IF (IFAIL.NE.O) STOP 
WRITE(6,2000) (ANS(I), I=1,15) 


2000 FORMAT(’ RESULTS’//(F12.7)) 


STOP 
END 


DAP program 


Results 


IFAIL = 
RESULTS 


ENTRY SUBROUTINE ENTTRIDSES 
REAL LOWER(), UPPER(), DIAG(), ANS(), RHS() 
COMMON /ANS/ANS/IFAIL/IFAIL 

EXTERNAL REAL VECTOR FUNCTION F04_TRIDS_ES 
N = 15 


LOWER = 0.5 
UPPER = 0.5 
DIAG = 2.0 
RHS = 3.0 
RHS(1) = 2.5 
RHS(N) = 2.5 


ANS = FO4_TRIDS_ES(LOWER,DIAG,UPPER,RHS,N,IFAIL) 
CALL CONVVFE(ANS,32,1) 

CALL CONVSFI(IFAIL, 1) 

RETURN 

END 


0 


. 9999999 
- 9999999 


BPRPRRPRPRrPHPrP PH HE 


-0000000 
0000000 
-0000000 
. 0000000 
.0000000 
-0000000 
-0000000 
.0000000 
- 0000000 
- 0000000 
0000000 


. 9999999 
- 9999999 


General Support library man010.02 


7.4 F04.TRIDS_ES 


77 


7.5 F04.TRIDS_ES.SQ F04 — Simultaneous linear equations 


7.5 F04 .~TRIDS_ES_SQ release 1 


78 


1 


Purpose 


F04.TRIDS_ES_SQ returns the solution of a set of up to 32 tridiagonal linear systems of 
equations each of order up to 32. That is, it solves up to 32 systems of the form: 


Mz=y 
where M is a tridiagonal matrix. 


Specification 


REAL MATRIX FUNCTION F04.TRIDS_ES_SQ (A,B,C, Y,N, K, IFAIL) 
INTEGER N , K , IFAIL 
REAL A(,), B(,), C(,), Y(,) 


Description 


The algorithm used is of the recursive doubling type. At each step the distance of the two 
outer diagonals from the main diagonal is doubled. When only a diagonal matrix remains 
the solution is obtained by a simple division. Each system is stored down the columns of the 
matrix arguments and so, many systems can be solved simultaneously. Full details can be 


found in [1]. 


References 
[1] WHITEWAY J 


A parallel algorithm for solving tridiagonal systems: DAPSU Newletter 3, December 
1979: available from the DAP Support Unit, Queen Mary College, Mile End Road, 
London E1 4NS. 


Arguments 
A - REAL MATRIX 


On entry, elements 2 to N of columns 1 to K of A must be set to the values of the lower 
diagonal of each of the K systems That is, if the K*® matrix is M = m(i,j) then A(I, K) 
must be set to M(I,J—1) (I = 2,3, ..., N). Elements with row subscripts not in the 
range 2 to N or columns subscripts not in the range 1 to K are ignored. A is unchanged 
on exit. 
B ~ REAL MATRIX 

On entry, elements 1 to N of columns 1 to K of B must be set to the values of the 
main diagonal of each of the AK systems. That is, if the K*® matrix is M = m(i,j) 
then B(I,K) must be set to M(I,I)(I = 1,2,..., N). Elements with row subscripts 


not in the range 1 to N or column subscripts not in the range 1 to K are ignored. B is 
unchanged on exit. 


C —- REAL MATRIX 


On entry, elements 1 to N — 1 of columns 1 to K of C must be set to the values of the 
upper diagonal of each of the K systems. That is, if the K*® matrix is M = m(i, 7) then 
C(I, K) must be set to M(I,I+1) (I= 1,2, ..., N—1). Elements with row subscripts 
not in the range 1 to N — 1 or column subscripts not in the range 1 to K are ignored. C 
is unchanged on exit. 
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Y — REAL MATRIX 


On entry, elements 1 to N of columns 1 to K of Y must be set to the values of the K 
RHS vectors. Elements with row subscripts not in the range 1 to N or column subscripts 
not in the range 1 to K are ignored. Y is unchanged on exit. 


N - INTEGER 
On entry, N must specify the order of the tridiagonal systems (in the range 1 to 32). 


K - INTEGER 
On entry, K must specify the number of tridiagonal systems to be solved (in the range 
1 to 32). 

IFAIL ~- INTEGER 


Unless the routine detects an error (see Error Indicators below) IFAIL contains zero 
on exit. 


6 Error Indicators 
Errors detected by the routine: 


IFAIL = 1 At some stage during the calculation, an element on one of the 
leading diagonals is zero. This implies that, at least, one of the 
systems was singular. The contents of F04._TRIDS_ES_SQ in this 
case are undefined 


IFAIL = 2 As a minimum, at some stage during the calculation, one matrix 
. has. ceased to be diagonally dominant. Note : this is only a warning 
©) and the routine continues to completion (if possible) 


IFAIL = 3 N is not in the range 1 to 32 or K is not in the range 1 to 32 


7 Auxiliary Routines 


None 


8 Accuracy 


General results seem to indicate that the more diagonally dominant the systems are the more 
accurate the results. IFAIL = 1 is possible for non-diagonally dominant systems even if the 
system is non-singular. 


9 Further Comments 


None 


10 Keywords 


Tridiagonal linear systems 


11 Example 


The example given solves 2 tridiagonal systems of order 15. The solutions are 1 and 2 
respectively. 
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Host program 


1000 


2000 


PROGRAM MAINTRIDSESSQ 

REAL ANS(32,32) 

COMMON /ANS/ANS/IFAIL/IFAIL 

CALL DAPCON(’tridsessq.dd’) 

CALL DAPENT(’?ENTTRIDSESSQ’ ) 

CALL DAPREC(’? ANS’ , ANS, 1024) 

CALL DAPREC(?IFAIL? , IFAIL,1) 
CALL DAPREL 

WRITE(6,1000) IFAIL 

FORMAT (? IFAIL =’,I5) 


IF (IFAIL.NE.O.AND.IFAIL.NE.2) STOP 


WRITE(6,2000) (ANS(I,1), ANS(I,2), I = 1,15) 
FORMAT(’ RESULTS’//(2F12.7)) 

STOP 

END 


DAP program 


80 


ENTRY SUBROUTINE ENTTRIDSESSQ 
REAL LOWER(,), UPPER(,), DIAG(,), RHS(,), ANS(,) 
COMMON /ANS/ANS/IFAIL/IFAIL 

EXTERNAL REAL MATRIX FUNCTION FO4_TRIDS_ES_SQ 


‘N= 15 


K=2 
LOWER 
UPPER 
DIAG = 2.0 

RHS(,1) = 3.0 
RHS(,2) = 6.0 


u 


0.5 
0.5 


RHS(1,1) = 2.5 
RHS(N,1) = 2.5 
RHS(1,2) = 5.0 
RHS(N,2) = 5.0 


ANS = FO4_TRIDS_ES_SQ (LOWER,DIAG,UPPER,RHS,N,K,IFAIL) 
CALL CONVMFE(ANS) 

CALL CONVFSI(IFAIL, 1) 

RETURN 

END 
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Results 

IFAIL = 0 

RESULTS 
1.0000019 2.0000019 
1.0000019 2.0000019 
1.0000019 2.0000019 
1.0000019 2.0000019 
1.0000019 2.0000019 
1.0000019 2.0000048 
1.0000019 2.0000019 
1.0000019 2.0000019 
1.0000019 2.0000019 
1.0000019 2.0000019 
1.0000019 2.0000019 
1.0000019 2.0000019 
1.0000019 2.0000019 
1.0000019 2.0000019 
1.0000019 2.0000019 
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Purpose 
F04_TRIDS_LV returns the solution of a tridiagonal linear system of equations of order up 


to 1024. That is, it finds vector z where: 


Mz=y 


and M is a tridiagonal matrix. 


Specification 


REAL MATRIX FUNCTION F04_TRIDS.LV(A ,B,C,Y,N, IFAIL) 
INTEGER N , IFAIL ; 
REAL A(,), B(,), C(,), Y() 


Description 


The algorithm used is of the recursive doubling type. At each step the distance of the two 
outer diagonals from the main diagonal is doubled. When only a diagonal matrix remains 
the solution is obtained by a simple division. Full details may be found in [1]. 


References 
[1] WHITEWAY J 
A parallel algorithm for solving tridiagonal systems: DAPSU Newsletter 3, December 1979: 


available from the DAP Support Unit, Queen Mary College, Mile End Road, London El © 
4NS. 





Arguments 


A —- REAL MATRIX 


On entry, elements 2 to N of A (treated as a long vector) must be set to the values of 
the lower diagonal of the tridiagonal matrix. That is, if the matrix is M = m(i, 7) then 
A (J) must be set to M(I,I—1) (I =2,3,..., N). Elements with subscripts not in the 
range 2 to N are ignored. A is unchanged on exit. 


B — REAL MATRIX 


On entry, elements 1 to N of B (treated as a long vector) must be set to the values of 
the main diagonal of the tridiagonal matrix. That is, if the matrix is M = m(i,j) then 
B(I) must be set to M(I,I) (I = 1,2,..., N). Elements with subscripts not in the 
range 1 to N are ignored. B is unchanged on exit. 


C —- REAL MATRIX 


On entry, elements 1 to N — 1 of C (treated as a long vector) must be set to the values 
of the upper diagonal of the tridiagonal matrix. That is, if the matrix is M = m(i,j) 
then C(I) must be set to M(I,I +1) (I =1,2,..., N—1). Elements with subscripts 
not in the range 1 to N — 1 are ignored. C is unchanged on exit. 


Y ~ REAL MATRIX 


On entry, elements 1 to N of Y (treated as a long vector) must be set to the values of 
the RHS vector. Elements with subscripts not in the range 1 to N are ignored. Y is 
unchanged on exit. 
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N - INTEGER 


On entry, N must specify the size of the system (in the range 2 to 1024). That is, for 
Mz=y, M must be N by N. 


IFAIL - INTEGER 


Unless the routine detects an error (see Error Indicators below) IFAIL contains zero 
on exit. 


6 Error Indicators 
Errors detected by the routine: 


IFAIL = 1 At some stage during the calculation, an element on the leading 
diagonal is zero. This implies the original matrix was singular. The 
contents of F04.TRIDS_LV in this case are undefined 


IFAIL = 2 At some stage during the calculation, the matrix has ceased to be 
diagonally dominant. Note: this is only a warning and the routine 
continues to completion (if possible) 


IFAIL = 3 N is not in the range 2 to 1024 


7 Auxiliary Routines 


None 


8 Accuracy 


General results seem to indicate that the more diagonally dominant the system is the more 
accurate the results. IFAIL = 1 is possible for non-diagonally dominant systems even if the 
system is non-singular. 


9 Further Comments 


None 


10 Keywords 


Tridiagonal linear systems 


11 Example 


The example given is such that the solution vector should be 1. The system is diagonally 
dominant. 


Host program 


PROGRAM MAINTRIDS_LV 

REAL ANS(1024) 
COMMON/ANS/ANS/IFAIL/IFAIL 
CALL DAPCON(’tridslv.dd’) 
CALL DAPENT(’ENTTRIDS_LV’ ) 
CALL DAPREC(’ ANS’ , ANS, 1024) 
CALL DAPREC(?IFAIL’ , IFAIL,1) 
CALL DAPREL 
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1000 


2000 


WRITE (6,1000) IFAIL 

FORMAT (’ IFAIL =’,I5) 

IF (IFAIL.NE.0) STOP 
WRITE(6,2000) (ANS(I), I = 1, 15) 
FORMAT(’? RESULTS’// (F12.7)) 

STOP 

END 


DAP program 


ENTRY SUBROUTINE ENTTRIDS_LV 

REAL LOWER(,), UPPER(,), DIAG(,), ANS(,), RHS(,) 
COMMON /ANS/ANS/IFAIL/IFAIL 

EXTERNAL REAL MATRIX FUNCTION FO4_TRIDS_LV 

N = 15 
LOWER = 0. 
UPPER = 0. 
DIAG = 2.0 
RHS = 3.0 
RHS(1) = 2.5 

RHS(N) = 2.5 

ANS = FO4_TRIDS_LV(LOWER,DIAG,UPPER,RHS,N,IFAIL) 
CALL CONVMFE(ANS) 

CALL CONVSFI(IFAIL, 1) 


5 
5 


RETURN 
END 
Results 
IFAIL = 0 
RESULTS 

1.00000020 
1.00000020 
1.00000020 


All other results are also equal to 1.0000020 
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Chapter 8 


G05 — Random numbers 


Contents: 


Subroutine 

G05. MC_ BEGIN 

G05. MC_I4 

G05. MC_I8 

G05. MC. NORMAL. R4 
G05. MC_R4 


G05. MC_REPEAT 
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Purpose 
G05_MC_BEGIN sets the basic generator routine G05. MC_I8 to an initial state. 


Specification 


SUBROUTINE G05_MC. BEGIN 


Description 
This routine sets the internal variable N used by G05_ MC_18 to the value 123456789 x (2°? + 1). 


References 
[1] SMITH K A, REDDAWAY S F and SCOTT DM 


Very High Performance Pseudo-Random Number Generator on DAP: Computer 
Physics Communications, vol 37, pp 239-244 (1985) 


Arguments 


None 


Error Indicators 


None 


Auxiliary Routines 
None 


Accuracy 
Not applicable 


Further Comments 
The routine uses a labelled COMMON block C_G05. MC. 


Keywords 


Initialisation, random numbers 


Example 


The example program prints the first five pseudo-random real numbers from a uniform distri- 
bution between 0 and 1, generated by G05. MC_R4 after initialization by G05. MC_BEGIN. 


Host program 


PROGRAM MAIN 


REAL*4 RAND(1024) 
COMMON/RESULT/RAND 
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CALL DAPCON(? ent.dd’) 

CALL DAPENT(’ENT?’) 

CALL DAPREC(’RESULT’ ,RAND, 1024) 
CALL DAPREL 





WRITE(6, 1000) (RAND(I) ,I=1,5) 
1000 FORMAT(’GOS_MC_BEGIN EXAMPLE PROGRAM RESULTS’ /1X/ 
*5(1X,F10.4/)) 


STOP 
END 


DAP Program 


ENTRY SUBROUTINE ENT 


REAL*4 RAND(,) 
COMMON/RESULT/RAND 


EXTERNAL REAL*4 MATRIX FUNCTION GOS_MC_R4 


CALL GO5_MC_BEGIN 
RAND=G05_MC_R4(0.0) 


© CALL CONVMFE (RAND) 


RETURN 
END 


Results 


GO5_MC_BEGIN EXAMPLE PROGRAM RESULTS 


0.6149 
0.8745 
0.1511 
0.0734 
0.2451 
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Purpose 


G05_MC_I4 returns an INTEGER*4 MATRIX containing 1024 pseudo-random integer num- 
bers taken from a uniform distribution between 0 and 23! — 1. 


Specification 


INTEGER*4 MATRIX FUNCTION G05_MC.I4 (1) 
INTEGER*4 I 


Description 


The routine calls G05. MC_I8 which uses the multiplicative congruential method: 


N = 13!3 N mod 289 
G05_MC_I4 = N/28 


where N is a variable, internal to G05. MC_I8, whose value is preserved between calls of the 
routine. Its initial value is set by a call to either G05. MC.BEGIN or GO5.MC_REPEAT. 


References 
[1] SMITH K A, REDDAWAY S F and SCOTT DM © 


Very High Performance Pseudo-Random Number Generator on DAP: Computer 
Physics Communications, vol 37, pp 239-244, 1985 
Arguments 


I - INTEGER*4 
A dummy argument required by FORTRAN-PLUS syntax 


Error Indicators 


None 


Auxiliary Routines 
The routine calls the General Support library routine G05_MC_I8. 


Accuracy 
Not applicable 


Further Comments 


None 


Keywords 


Pseudo-random number, random number, rectangular distribution, uniform distribution 


Example 


The example program prints the first five pseudo-random numbers from a uniform distribu- 
tion between 0 and 2°!—1, generated by GO5_ MC_I4 after initialization by G05. MC_ BEGIN. 
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Host Program 





PROGRAM MAIN 


INTEGER*4 RAND(1024) 
COMMON/RESULT/RAND 


CALL DAPCON(’ent.dd’) 

CALL DAPENT(?ENT? ) 

CALL DAPREC(’RESULT? , RAND, 1024) 
CALL DAPREL 


WRITE(6, 1000) (RAND(I) ,I=1,5) 
1000 FORMAT(/’ GOS_MC_I4 EXAMPLE PROGRAM RESULTS’ /1X/ 
* 5(1X,1I20/)) 
STOP 
END 


DAP program 


ENTRY SUBROUTINE ENT 


INTEGER*4 RAND(,) 
© COMMON/RESULT/RAND 


EXTERNAL INTEGER*4 MATRIX FUNCTION GO5_MC_I4 


CALL GO5_MC_BEGIN 
RAND=GO5_MC_1I4(0) 
CALL CONVMFI(RAND) 


RETURN 
END 


Results 


GO5_MC_T4 EXAMPLE PROGRAM RESULTS 


1815152335 
436969313 
976973459 

1028379600 

1443266400 
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Purpose 


G05. MC_I8 returns an INTEGER*8 MATRIX containing 1024 pseudo-random integer num- 
bers taken from a uniform distribution between 10 and 259 — 1. 


Specification 
INTEGER*8 MATRIX FUNCTION G05_MC_I8 (I) 
INTEGER#8 I 

Description 

The routine uses the multiplicative congruential method: 
N = 13!3 N mod 2°9 
G05.MC_I8 = N 


where N is a variable, internal to G05.MC_I8, whose value is preserved between calls of the 
routine. Its initial value is set by a call to either GO5. MC_BEGIN or G05. MC_REPEAT. 


References 

[1] SMITH K A, REDDAWAY S F and SCOTT D M 
Very High Performance Pseudo-Random Number Generator on DAP: Computer 
Physics Communications, vol 37, pp 239-244, 1985 

Arguments 


I - INTEGER*8 
A dummy argument required by FORTRAN-PLUS syntax 


Error Indicators 


None 


Auxiliary Routines 


None 


Accuracy 
Not applicable 


Further Comments 
The routine uses labelled COMMON block C_G05.MC. 


Keywords 


Pseudo-random number, random number, rectangular distribution, uniform distribution 


Example 


This FORTRAN-PLUS fragment traces the pseudo-random numbers from a uniform distribu- 
tion between 0 and 259—1 generated by G05. MC_IB8 after initialization by G05. MC. BEGIN. 
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DAP program 





ENTRY SUBROUTINE ENT 

INTEGER*8 RAND(,) 

EXTERNAL INTEGER*8 MATRIX FUNCTION GO5_MC_I8 
CALL GO5_MC_BEGIN 

RAND=G05_MC_I8(0) 

TRACE 1(RAND) 


RETURN 
END 


Results 


FORTRAN-PLUS Trace 
FORTRAN-PLUS Subroutine: ENT at Line 9 


Integer Matrix Local Variable RAND in 64 bits - addressed by Stack + 0.09 
: (Row 01 Col 01)  487251244993469717, 476067912847080853, 


(Col 03) 190484975398149653, 493464185425411733, 
(Col 05)  517514364922158869, 463547216227221397, 


There are 512 lines of detailed output altogether. 
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1 Purpose 


G05. MC. NORMAL. R4 provides a REAL*4 matrix containing normal pseudo-random vari- 
ates from the distribution N(0,1). 


2 Specification 
REAL*4 MATRIX FUNCTION G05_MC_NORMAL.R4(D) 
REAL*4-D 
3 Description 
The real matrix GO5.MC.NORMAL_R4 is set equal to 1024 of either of: 


SQRT(-2.0 LOG(U,)) SIN(27 U2) 
SQRT(-2.0 LOG(U,)) COS(27 U2) 


where U; and U2 are uniform pseudo-random numbers generated by G05. MC_R4 (see Atkin- 
son{1]). 


4 References 


[1] ATKINSON A C and PEARCE MC 


The computer generation of Beta, Gamma and Normal random variables: J R Statist 
Soc 139, pp 431-461, 1976 





5 Arguments 
D - REAL*4 
D is a dummy argument required by FORTRAN-PLUS syntax. 


6 Error Indicators 


None 


7 Auxiliary Routines 
The routine calls the General Support library routine G05. MC_R4. 


8 Accuracy 
Not applicable 


9 Further Comments 
The routine uses the labelled COMMON block C.G05.N.NORM. 


10 Keywords 


Gaussian distribution, normal distribution, random numbers 
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11 Example 


This example program prints the first five pseudo-random normal variates from a normal 
distribution with mean 0 and standard deviation 1, generated by GO5.MC_NORMAL_R4 
after initialization by GO5.MC.BEGIN. 


Host program 


PROGRAM MAIN 


REAL*4 RAND(1024) 
COMMON/RESULT/RAND 


CALL DAPCON(’ent.dd’) 

CALL DAPENT(’ ENT?) 

CALL DAPREC(?RESULT’ ,RAND, 1024) 
CALL DAPREL 


WRITE(6, 1000) (RAND(I) ,I=1,5) 
1000 FORMAT(/,’ GOS_MC_NORMAL_R4 EXAMPLE PROGRAM RESULTS? /1X/ 
*5(1X,F10.4/)) 


STOP 
END 


DAP program 


ENTRY SUBROUTINE ENT 


REAL*4 RAND(,) 
COMMON/RESULT/RAND 


EXTERNAL REAL*4 MATRIX FUNCTION GOS5_MC_NORMAL_R4 


CALL GO5_MC_BEGIN 
RAND=GO5_MC_NORMAL_R4(0.0) 
CALL CONVMFE(RAND) 


RETURN 
END 


Results 


GOS_MC_NORMAL_R4 EXAMPLE PROGRAM RESULTS 


-1.4384 
1.7104 
.1361 

. 1528 
~.8427 
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Purpose 
G05_MC_R4 returns a REAL*4 MATRIX of 1024 pseudo-random real numbers taken from 
a uniform distribution between 0 and 1. 
Specification 
REAL*4 MATRIX FUNCTION G05. MC.R4(X) 
REAL*4 X 


Description 
The routine returns the matrix of values: 
N Vp he 


where N is the result of a call to G05. MC_IS8. 


References 
[1] SMITH K A, REDDAWAY S F and SCOTT DM : 
Very High Performance Pseudo-Random Number Generator on DAP: Computer 


Physics Communications, vol 37, pp 239-244, 1985 
Arguments 
X —- REAL*4 

A dummy argument required by FORTRAN-PLUS syntax 


Error Indicators 


None 


Auxiliary Routines 
The routine calls the General Support library routine G05. MC_RS8. 


Accuracy 
Not applicable 


Further Comments 


None 


Keywords 


Pseudo-random number, random number, rectangular distribution, uniform distribution 


Example 


The example program prints the first five pseudo-random real numbers from a uniform distri- 
bution between 0 and 1, generated by G05. MC_R4 after initialization by G05. MC_BEGIN. 


man010.02 AMT 














G05 — Random numbers 8.5 G05.MC_R4 


Host program 





PROGRAM MAIN 


REAL*4 RAND(1024) 
COMMON/RESULT/RAND 


CALL DAPCON(’ ent.dd’) 

CALL DAPENT(’ENT?’) 

CALL DAPREC(’ RESULT’ , RAND , 1024) 
CALL DAPREL 


WRITE(6, 1000) (RAND(I) ,I=1,5) 
1000 FORMAT(/,’ GOS5_MC_R4 EXAMPLE PROGRAM RESULTS’ /1X/ 
*5(1X,F10.4/)) 


STOP 
END 


DAP program 
ENTRY SUBROUTINE ENT 
© REAL*4 RAND(,) 
COMMON/RESULT/RAND 
EXTERNAL REAL*4 MATRIX FUNCTION GO5_MC_R4 
CALL GO5_MC_BEGIN 
RAND=GO5_MC_R4(0.0) 
CALL CONVMFE(RAND) 


RETURN 
END 


Results 


GO5_MC_R4 EXAMPLE PROGRAM RESULTS 


8452 
. 2035 
. 4549 
.4789 
6721 





General Support library man010.02 ; 95 


8.6 G05.MC_R8 G05 — Random numbers 


8.6 G05_MC_R8 release 1 


10 


li 


96 


Purpose 


G05_MC.R8 returns a REAL*8 MATRIX of 1024 pes: random real numbers taken from 
a uniform distribution between 0 and 1. : 


Specification 


REAL*8 MATRIX FUNCTION G05_.MC_R8(X) 
REAL*8 X 


Description 
The routine returns the matrix of values: 
N/259 


where N is the result of a call to G05. MC_IS8. 


References 

[1] SMITH K A, REDDAWAY S F and SCOTT D M 
Very High Performance Pseudo-Random Number Generator on DAP: Computer 
Physics Communications, vol 37, pp 239-244, 1985 

Arguments 

X —- REAL*8 
A dummy argument required by FORTRAN-PLUS syntax 


Error Indicators 


None 


Auxiliary Routines 
The routine calls the General Support library routine G05. MC_IS8. 


Accuracy 
Not applicable 


Further Comments 


None 


Keywords 


Pseudo-random number, random number, rectangular distribution, uniform distribution 


Example 


The example program prints the first five pseudo-random real numbers from a uniform distri- 
bution between 0 and 1, generated by G05. MC_R8 after initialization by G05. MC_BEGIN. 
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Host program 





PROGRAM MAIN 


DOUBLE PRECISION RAND(1024) 
COMMON/RESULT/RAND 


CALL DAPCON(? ent.dd’) 

CALL DAPENT(’?ENT?) 

CALL DAPREC(’RESULT’ ,RAND , 2048) 
CALL DAPREL 


WRITE(6, 1000) (RAND(I) ,I=1,5) 
1000 FORMAT(/,’ GOS_MC_R8 EXAMPLE PROGRAM RESULTS? /1X/ 
*5(1X,F10.4/)) 


STOP 
END 


DAP program 
ENTRY SUBROUTINE ENT 


© DOUBLE PRECISION RAND(,) 
COMMON/RESULT/RAND 


EXTERNAL REAL*8 MATRIX FUNCTION GO5_MC_R8 


CALL GO5_MC_BEGIN 
RAND=G05_MC_R8(0.0) 
CALL CONVMFD (RAND) 


RETURN 
END 


Results 


GOS5_MC_R8 EXAMPLE PROGRAM RESULTS 


8452 
. 2035 
. 4549 
-4789 
6721 
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Purpose 
G05. MC. REPEAT sets the basic generator routine G05. MC_I8 to a repeatable initial state. 


Specification 
SUBROUTINE G05. MC. REPEAT( I ) 
INTEGER*4 I 

Description 


The routine sets the internal variable N used by GO5.MC_I8 to a value calculated from the 
parameter I, where: 


N = 2ABS(I) +1 


The routine will yield different subsequent sequences of random numbers if called with differ- 
ent values of I, but the sequences will be repeatable in different runs of the calling program. 


References 

[1] SMITH K A, REDDAWAY S F and SCOTT D M 
Very High Performance Pseudo-Random Number Generator on DAP: Computer 
Physics Communications, vol 37, pp 239-244, 1985 

Arguments 

I - INTEGER*4 


On entry I specifies a number from which the new internal generator is calculated; I is 
unchanged on exit. 


Error Indicators 
None 


Auxiliary Routines 
None 


Accuracy 
Not applicable 


Further Comments 
The routine uses a labelled COMMON block C_.G05.MC. 


Keywords 


Pseudo-random number, random number, rectangular distribution, uniform distribution 


Example 


The example program prints the first five pseudo-random real numbers from a uniform distri- 
bution between 0 and 1, generated by G05. MC_R4 after initialization by G05. MC. REPEAT. 
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Host program 





PROGRAM MAIN 


REAL*4 RAND(1024) 
COMMON/RESULT/RAND 


CALL DAPCON(? ent.dd’) 

CALL DAPENT(’ENT? ) 

CALL DAPREC(’RESULT? , RAND, 1024) 
CALL DAPREL 


WRITE(6, 1000) (RAND(I) , I=1,5) 
1000 FORMAT(/,’ GOS_MC_REPEAT EXAMPLE PROGRAM RESULTS’/1X/ 
*5(1X,F10.4/)) 


STOP 
END 


DAP program 


ENTRY SUBROUTINE ENT 
REAL*4 RAND(,) 
COMMON/RESULT/RAND 
EXTERNAL REAL*4 MATRIX FUNCTION GO5_MC_R4 
CALL GO5_MC_REPEAT(10) 
RAND=GO5_MC_R4(0.0) 


CALL CONVMFE (RAND) 


RETURN 
END 


Results 


GO5_MC_REPEAT EXAMPLE PROGRAM RESULTS 


-6178 
- 6430 
- 5399 
- 3852 
. 1947 
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H0O1 — Operations research, graph 
structures, networks 


Contents: . 
Subroutine Page 
H01_L. ASSIGN 102 
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1 Purpose 


102 


H01_L.ASSIGN solves the linear assignment problem with a minimum objective function 
and a real cost matrix of order N x N, where N < 32. 


Specification 


SUBROUTINE H01_L_ASSIGN(C , X , N , MIN , IFAIL) 
REAL C(,) , MIN 
INTEGER X(), N, IFAIL 


Description 


The algorithm used is that of Ford and Fulkerson, [1], [2], which uses the Primal-Dual 
method. After dualizing the Primal problem, the routine aims to find a pair X, (U,V) of 
Primal and Dual solutions respectively which satisfy the complimentary slackness condition. 


To find the appropriate solutions, a network G(U, V) is set up. There is an arc (i,j) in 
the graph whenever u,; + Vj = ¢jj, where cj; is the cost of assigning i to j. Next, the 
labelling algorithm of Ford and Fulkerson is appplied to find a maximum flow in G(U, V). If 
the maximum flow saturates the sink or (source), the problem is solved, otherwise the dual 
solutions are updated and the process restarts. 


References 
[1] DANTZIG GB 


Linear Programming and Extensions: Princeton University Press, 1963 


[2] FORD L R and FULKERSON DR 


Flows in Networks: Princeton University Press, 1962 


Arguments 
C ~ REAL MATRIX 
On entry C contains the N x N assignment cost matrix; C is unchanged on exit. 


X - INTEGER VECTOR 


On exit, X specifies the assignment solution; that is, if X (I) = J, for I,J <N, then I is 
assigned to J. 


N ~ INTEGER 


On entry N is the order of the cost matrix C. N must lie between 2 and 32, and is 
unchanged on exit. 


MIN - REAL 


On exit MIN contains the assignment value. 


IFAIL ~ INTEGER 


Unless the routine detects an error (see Error Indicators below) IFAIL contains zero 
on exit. 
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Error Indicators 
Errors detected by the routine: 


IFAIL = 1 N does not lie in the range 2 to 32 


Auxiliary Routines 
The routine calls the GS library routines X05. E.MIN_VC and X05. E.MIN_VR. 


Accuracy 


You can expect the computed value of the objective function MIN to be accurate to about 
6 significant digits. 


Further Comments 


None 


Keywords 


Labelling algorithm, linear assignment, maximum flow, Primal-Dual algorithms 


Example 


The example is a 5 x 5 assignment problem, where the cost matrix is as follows: 


3 23 4 1 
412 4 2 
C=|]1 0 5 3 2 
75 01 3 
0412 8 
Hence N = 5 


Host program 


PROGRAM LASP 


REAL C(32,32) ,MIN 
INTEGER X(32) ,N,IFAIL 
COMMON/A1/C 
COMMON/A2/X 
COMMON/A3/N, IFAIL 
COMMON/A4/MIN 


READ(*,*) N 
DO 10 I=1,N 
10 READ(*,*) (C(I,J), J=1,N) 


CALL DAPCON(?initial.dd’) 
CALL DAPSEN(?A1’,C, 1024) 
CALL DAPSEN(’A3? ,N,1) 


General Support library man010.02 103 


idea taes| 





9.1 H01.L. ASSIGN HO1 - Operations research, graph structures, networks 





CALL DAPENT(? INITIAL’) 

CALL DAPREC(’A1?,C, 1024) 

CALL DAPREC(’A2’,X,32) 

CALL DAPREC(?A3’ ,N,2) 

CALL DAPREC(’A4?’ ,MIN,1) 

CALL DAPREL 

WRITE (*,*) ’IFAIL = ’,IFAIL 
IF (IFAIL .NE. 0) STOP 
WRITE(6,30) MIN, (X(I), I=1,N) 


30 FORMAT(/,’ MINIMUM VALUE OF ASP. =’,Fi2.5,//,’ THE ASSIGNMENTS? , 
* > ARE AS FOLLOWS:’,//, (1X,1614)) 


STOP 
END 


DAP program 


ENTRY SUBROUTINE INITIAL 





REAL C(,),MIN 
INTEGER X( ),N,IFAIL 
COMMON/A1/C 
COMMON/A2/X 
COMMON/A3/N, IFAIL 
COMMON/A4/MIN 


CALL CONVFSI(N, 1) 
CALL CONVFME(C) 


CALL HO1_L_ASSIGN(C,X,N,MIN, IFAIL) 


CALL CONVMFE(C) 
CALL CONVVFI(X,32,1) 
CALL CONVSFI(N,2) 
CALL CONVSFE(MIN, 1) 


RETURN 
END 
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Data 





OoONHP PWM 
Poo FN 
KrF OM nN WwW 
New Pp Pp 
WWN ND 


Results 


IFAIL = 0 


MINIMUM VALUE OF ASP. = 4.00000 


THE ASSIGNMENTS ARE AS FOLLOWS: 


5 3 2 4 1 
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Purpose 


J06.-CHAR-CONT returns a character matrix containing a rough contour map of a real 
matrix. You can control the number of contours and contour levels. 


Specification 

SUBROUTINE J06.CHAR.CONT(A , MAP , CODE , LEVELS , NUM_LEVELS F 
+  IFAIL) 

INTEGER NUM_LEVELS , IFAIL 

REAL A(,) , LEVELS() 

CHARACTER MAP (,) , CODE() 


Description 


The routine adds contours one by one in order of descending height. For each contour the 
routine finds the area of the map which is less than the contour height. The border of this 
area is then found by eliminating any elements lying entirely within the area. This border 
is then taken as the contour. 


References 
None 


Arguments 


A —- REAL MATRIX 


On entry, A contains the matrix for which a contour map is required. A is unchanged 
on exit. 


MAP ~ CHARACTER MATRIX 
On exit, MAP contains the required contour map. 


CODE - CHARACTER VECTOR 


On entry, CODE must either have been set to all spaces or the first NUM_LEVELS entries 
must contain the characters required to represent the contour levels. If CODE is all spaces 
then the default character sequence of 0123456789ABCDEFGHIJ KLMNOPQRSTU- 
VWXYZ will be used. CODE is unchanged on exit. 


LEVELS - REAL VECTOR 
On entry, LEVELS must contain the NUM-LEVELS contour height values required (if 
NUM.LEVELS is positive), or may be undefined if NUM_LEVELS is negative. 
If NUM.LEVELS is positive, successive entries in LEVELS must be strictly increasing. 
On exit, elements 1 to ABS(NUM-_LEVELS) of LEVELS contain the contour height 
values used in the contour plot, (other elements of LEVELS are undefined). 
NUM.LEVELS - INTEGER 
On entry, NUM_LEVELS specifies the number of contour lines required. NUM. LEVELS 
must not be zero or greater than 36 in absolute magnitude. 


If NUM-LEVELS is positive, the contour heights will be taken from the vector LEVELS. 
If NUM.LEVELS is negative, ABS(NUM-LEVELS) contours will be drawn equally 
spaced between the maximum and minimum values of A. NUM.LEVELS is unchanged 
on exit. 
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IFAIL - INTEGER 


Unless the routine detects an error (see Error Indicators below) IFAIL contains zero 
on exit. 





6 Error Indicators 


Errors detected by the routine: 


IFAIL = 1. NUM_LEVELS is zero or not in the ranges -36 to -1 or 1 to 36 
IFAIL = 2 The firs; NUM_LEVELS entries of LEVELS are not in strictly ascending order 
IFAIL = 3 NUM_LEVELS is negative and all the entries in A are identical 


7 Auxiliary Routines 


None 


8 Accuracy 
Not applicable 


9 Further Comments 


None 


10 Keywords . 


Contour plots 


© 11 Example 
The example generates two maps of the function z? + y”, the first using the default character 
set and equally spaced contour heights and the second using heights and characters you 
define. The maps are output using the FORTRAN-PLUS TRACE statement. 


Host program 


PROGRAM MAIN 

CALL DAPCON(’ example.dd’ ) 
CALL DAPENT(? EXAMPLE? ) 
CALL DAPREL 

STOP 

END 


DAP program 


ENTRY SUBROUTINE EXAMPLE 

REAL A(,),CLEVELS() 

INTEGER IV() 

CHARACTER MAP(,),MYCODE() 

CALL XO5_SHORT_INDEX(IV,0) 

A=FLOAT(MATR(IV-32)**2 + MATC(IV-32)*#2) 

CALL JOG6_CHAR_CONT(A,MAP,VEC(’ ’),CLEVELS,-10,IFAIL) 
TRACE 1 (MAP, IFAIL,CLEVELS) 
CLEVELS(1)=100.0 
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CLEVELS (2)=500.0 

CLEVELS (3)=1000.0 

CLEVELS (4)=1200.0 
MYCODE(1)=7A? 

MYCODE(2)=’B? 

MYCODE(3)='C? 

MYCODE(4)=’D? 

CALL JO6_CHAR_CONT(A,MAP ,MYCODE,CLEVELS ,4, IFAIL) 
TRACE 1 (MAP, IFAIL,CLEVELS) 
RETURN 

END 
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10.2 JO6_ZEBRA CHART release 1 





1 Purpose 


JO6.ZEBRA -CHART returns a contour map suitable for output to a printing device of a 
real matrix. The output is called a ZEBRA chart; it consists of alternating bands of blanks 
and a given character. 


2 Specification 


CHARACTER MATRIX FUNCTION J06_ZEBRA _CHART(X , STEPS , CHAR) 
INTEGER STEPS 

REAL X(,) 

CHARACTER CHAR 


3 Description 


The method used is straightforward: the input variable is scaled and divided into STEPS 
levels, and the least significant bit of the level number is used as a mask to create the output. 


4 References 


None 


5 Arguments 


© X —- REAL MATRIX 
On entry, X contains the matrix to be plotted, and is unchanged on exit. 
STEPS - INTEGER 


On entry, STEPS specifies the number of bands in the chart (between the minimum and 
maximum of X), and is unchanged on exit. 


CHAR - CHARACTER 
On entry, CHAR specifies the character to be used in the bands, and is unchanged on 
exit. 
6 Error Indicators 
Errors detected by the routine: 


If STEPS is less than 2 or the range of X is less than 1.0E-5 then a chart of all ‘E’s is 
produced. 


7 Auxiliary Routines 


None 


8 Accuracy 
Not applicable 


9 Further Comments 


None 
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Keywords 


Contour map, Zebra chart 


Example 


The example calculates a simple function and uses the FORTRAN-PLUS TRACE facility 
to output the Zebra chart generated. 


Host program 


PROGRAM MAIN 

CALL DAPCON(’ example.dd’) 
CALL DAPENT(’? EXAMPLE’ ) 
CALL DAPREL 

STOP 

END 


DAP program 


ENTRY SUBROUTINE EXAMPLE 
EXTERNAL CHARACTER MATRIX FUNCTION JO6_ZEBRA_CHART 
REAL X(,) 

CHARACTER OUT(,) 

INTEGER I() 

F=3.14159/32. 

G=2.0*F 

CALL SHORT_INDEX(I) 
X=MATR(SIN(F*I))+MATC(COS(G*I) ) 
OUT=JO6_ZEBRA_CHART(X,10,’*’) 

TRACE 1 (OUT) 

RETURN 

END 
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Purpose 


M01-BSORT-_LV is a sorting routine based on bitonic sorting. Data is sorted according to 
a key, or the key alone may be sorted. 


Specification 


SUBROUTINE M01_BSORT_LV(KEY , L , X , D) 
INTEGER KEY(,) ,L,D 
LOGICAL X(,,D) 


Description 


The routine uses Batcher’s bitonic sorting algorithm. For a description see [1]. 


References 
[1] KNUTH DE 
The Art of Computer Programming, Vol 3 (Sorting and Searching): p 232 Addison- 


Wesley, 1973 
Arguments 


KEY ~ INTEGER MATRIX 


On entry, KEY (considered as a long vector) must be defined as the key to the sort; on 
exit the contents of KEY will have been sorted. 


L - INTEGER 


On entry, L must have been set to zero if only the KEY is to be sorted; any other value 
will cause the data to be sorted as well. L is unchanged on exit. 


X — <any type> MATRIX (or MATRIX array) 


On entry, X contains the data to be sorted. On exit, X contains the sorted data. 


D - INTEGER 


On entry, D specifies the number of bit planes in the data, and is unchanged on exit. 


Error Indicators 


None 


Auxiliary Routines 


None 


Accuracy 
Not applicable 


Further Comments 


None 
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10 Keywords 





Batcher sort, bitonic sort, data sort, key sort 


11 Example 


The example sorts 6 real values according to an integer key. Key entries beyond the data of 
interest are set to a large number to prevent them being involved in the sort. 


Host program 


PROGRAM MAIN 


REAL DATA(1024) 
INTEGER KEY(1024) 
COMMON /KEY/KEY /DATA/DATA 


DO 10 J=1,1024 
10 KEY(J)=10000 
READ(*,*) (KEY(I) ,I=1,6) 
READ(*,*) (DATA(I) ,I=1,6) 
WRITE(6,1000) (DATA(I) ,I=1,6), (KEY(I) ,I=1,6) 
1000 FORMAT(’ INPUT VALUES:’//’ DATA:’,6F10.3/’ KEY:’ ,6I10) 


CALL DAPCON(’ent.dd’) 
CALL DAPSEN(’KEY? , KEY, 1024) 
© CALL DAPSEN(?DATA’ , DATA, 1024) 


CALL DAPENT(’ ENT?) 


CALL DAPREC(’KEY’ , KEY, 1024) 
CALL DAPREC( DATA? ,DATA, 1024) 


CALL DAPREL 


WRITE(6,2000) (DATA(I) ,I=1,6), (KEY(I) ,I=1,6) 

2000 FORMAT(//’ OUTPUT VALUES:’//’ DATA:’ ,6F10.3/? KEY: ? ,6110) 
. STOP 
END 


DAP program 


ENTRY SUBROUTINE ENT 


INTEGER KEY(,) 
REAL DATA(,) 
COMMON /KEY/KEY /DATA/DATA 
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CALL CONVFMI(KEY) 
CALL CONVFME(DATA) 





CALL MO1_BSORT_LV(KEY,1,DATA,32) 


CALL CONVMFI (KEY) 
CALL CONVMFE(DATA) 


RETURN 
END 


Data 


Results 


INPUT VALUES: 


DATA: 7.500 22.000 -81.000 -2.000 3.000 19.000 
KEY: 8 -1 7 16 2° -3 





OUTPUT VALUES: 


DATA: 19.000 22.000 3.000 -81.000 7.500 -2.000 
KEY: -3 -1 2 7 8 16 
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11.2 MO1_ INV_PERMUTE _COLS release 1 


1 Purpose 
M01.INV_PERMUTE.COLS permutes the first M columns of a matrix according to a 
permutation vector (IV). The result is equivalent to the FORTRAN-PLUS statements: 


DO 101=1,M 
10 A_.PERMUTED(,IV(1)) = A(,1) 


2 Specification 


SUBROUTINE M01_INV_PERMUTE .COLS (A, AP,IV,N, M) 
INTEGERIV(),N,M 
<any type> A(,) » AP (,) 


3 Description 


Columns are permuted according to the integer index vector IV, such that column I is moved 
to column IV(I). 


4 References 


None 


5 Arguments 
A — <any type> MATRIX 


On entry, A contains the matrix whose columns are to be permuted. A may be of any 
type, and is unchanged on exit. 


AP ~ <any type> MATRIX 


On exit, AP contains the columns of A permuted according to the index vector IV. AP 
should usually be of the same type as A. If M is less than 32, columns M+1 to 32 are 
unchanged on exit. ; 


IV ~ INTEGER VECTOR 


On entry, IV contains the required permutation, that is, column I of A will be moved to 
column IV(I) of AP. Elements 1 to M of IV must be in the range 1 to 32. If the entries 
of IV are not all distinct - for example, if IV(I) = IV(J) with J > I - then column 
AP(,IV(J)) will have the value A(,J) on exit. IV is unchanged on exit. 


N —- INTEGER 
On entry, N contains the number of planes in the matrix to be permuted; possible values 
for N are: 
N=1 for permuting a logical matrix 
N=8 for permuting a character matrix 
N = 8*n for permuting an INTEGER*n or REAL*n matrix 


N should be less than 257, and is unchanged on exit. 
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5 Arguments - continued 
M - INTEGER 


On entry, M must contain a value in the range 1 to 32; only the first M index values of 
IV are used. M is unchanged on exit. . 


6 Error Indicators 


None 


7 Auxiliary Routines 
The routine references the General Support library routine Z.M01_AUX. 


8 Accuracy 
Not applicable 


9 Further Comments 
The parameters given as A and AP may be single arrays or part of a matrix set. For example, 
in: 


CALL M01 -INV.PERMUTE.COLS (L (,,5), LL(,,10), IV,1,32) 


L and LL are logical matrix sets of size (at least) 5 and 10 respectively. 
You must not use a common block with the names of CZ _M01.HEX1F or CZ_M01-REVERSE. 


10 Keywords 


Permutation 


11 Example 


The following FORTRAN-PLUS fragment reverses the order of the columns of a real matrix, 
that is, 
AP = REVR(A). 


ENTRY SUBROUTINE ENT 
REAL AC,), AP(,) 
INTEGER IV() 

DO 10 I=1, 32 


10 IV(I) = 33 -- I 
DO 20 IT = 1, 32 
DO 20 J=1, 32 


20 ACI,J) = FLOAT (I + J) 
CALL MO1_INV_PERMUTE_COLS (A, AP, IV, 32, 32) 
TRACE 1 (AP) 
RETURN 
END 


Results 
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FORTRAN-PLUS Trace 
FORTRAN-PLUS Subroutine: ENT at Line 10 





Real Matrix Local Variable AP in 32 bits -- addressed by Stack + 0.10 


(Row 01 Col 01) 3.3000000E+01, 3.2000000E+01, 3.1000000E+01, 
(Col 04) 3.0000000E+01, 2.9000000E+01, 2.8000000E+01, 
(Col 07) 2.7000000E+01, 2.6000000E+01, 2.5000000E+01, 
(Col 10) 2.4000000E+01, 2.3000000E+01, 2.2000000E+01, 
(Col 13) 2.1000000E+01, 2.0000000E+01, 1.9000000E+01, 
(Col 16) 1.8000000E+01, 1.7000000E+01, 1.6000000E+01, 
(Col 19) 1.5000000E+01, 1.4000000E+01, 1.3000000E+01, 
(Col 22) 1.2000000E+01, 1.1000000E+01, 1.0000000E+01, 
(Col 25) 9.0000000E+00, 8.0000000E+00, 7.0000000E+00, 
(Col 28) 6.0000000E+00, 5.0000000E+00, 4.0000000E+00, 
(Col 31) 3.0000000E+00, 2.0000000E+00 
(Row 02 Col 01). 3.4000000E+01, 3.3000000E+01, 3.2000000E+01, 
(Col 04) 3.1000000E+01, 3.0000000E+01, 2.9000000E+01, 
(Col 07) 2.8000000E+01, 2.7000000E+01, 2.6000000E+01, 
(Col 10) 2.5000000E+01, 2.4000000E+01, 2.3000000E+01, 
(Col 13) 2.2000000E+01, 2.1000000E+01, 2.0000000E+01, 
(Col 16) 1.9000000E+01, 1.8000000E+01, 1.7000000E+01, 
(Col 19) 1.6000000E+01, 1.5000000E+01, 1.4000000E+01, 
(Col 22) 1.3000000E+01, 1.2000000E+01, 1.1000000E+01, 
(Col 25) 1.0000000E+01, 9.0000000E+00, 8.0000000E+00, 
(Col 28) 7.0000000E+00, 6.0000000E+00, 5.0000000E+00, 
© (Col 31) 4.0000000E+00, 3.0000000E+00 
(Row 03 Col 01) 3.5000000E+01, 3.4000000E+01, 3.3000000E+01, 
(Col 04) 3.2000000E+01, 3.1000000E+01, 3.0000000E+01, 
(Col 07) 2.9000000E+01, 2.8000000E+01, 2.7000000E+01, 
(Col 10) 2.6000000E+01, 2.5000000E+01, 2.4000000E+01, 
(Col 13) 2.3000000E+01, 2.2000000E+01, 2.1000000E+01, 
(Col 16) 2.0000000E+01, 1.9000000E+01, 1.8000000E+01, 
(Col 19) 1.7000000E+01, 1.6000000E+01, 1.5000000E+01, 
(Col 22) 1.4000000E+01, 1.3000000E+01, 1.2000000E+01, 
(Col 25) 1.1000000E+01, 1.0000000E+01, 9.0000000E+00, 
(Col 28) 8.0000000E+00, 7.0000000E+00, 6.0000000E+00, 
(Col 31) 5.0000000E+00, 4.0000000E+00 
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01) 
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-2000000E+01, 6.1000000E+01, 
-9000000E+01, 5.8000000E+01, 
-6O00000E+01, 5.5000000E+01, 
-3000000E+01, 5.2000000E+01, 
-OOOOO000E+01, 4.9000000E+01, 
- TOOOOO0E+01, 4.6000000E+01, 
-4000000E+01, 4.3000000E+01, 
-1000000E+01, 4.0000000E+01, 
-8000000E+01, 3.7000000E+01, 
-5000000E+01, 3.4000000E+01, 
-2000000E+01, 3.1000000E+01 
-3000000E+01, 6.2000000E+01, 
-OOOO000E+01, 5&.9000000E+01, 
- TOOOOO0E+01, 5.6000000E+01, 
-4000000E+01, 5&.3000000E+01, 
-1000000E+01, 5&.0000000E+01, 
-8000000E+01, 4.7000000E+01, 
-5000000E+01, 4.4000000E+01, 
-2000000E+01, 4.1000000E+01, 
-9000000E+01, 3.8000000E+01, 
-6000000E+01, 3.5000000E+01, 
-3000000E+01, 3.2000000E+01 
-4000000E+01, 6.3000000E+01, 
- 1000000E+01, 6.0000000E+01, 
-8000000E+01, 5.7000000E+01, 
-5000000E+01, 5.4000000E+01, 
-2000000E+01, 5.1000000E+01, 
-9O00000E+01, 4.8000000E+01, 
-6000000E+01, 4.5000000E+01, 
-3000000E+01, 4.2000000E+01, 
-OOOOOODE+01, 3.9000000E+01, 
- TOOO000E+01, 3.6000000E+01, 
-4000000E+01, 3.3000000E+01 
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.OOOO0000E+01, 
. TOOOOO0E+01, 
-4000000E+01, 
. LOOOOO0E+01, 
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- 5000000E+01, 
. 2000000E+01, 
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. 1000000E+01, 
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11.3 MO1_ INV_ PERMUTE _LV_32 release 1 





1 Purpose 


M01 -INV.PERMUTE _LV_32 permutes the values in a long vector of 4-byte values using 
an INTEGER*4 long vector key. The result is written to a new long vector; the original 
data is unaffected. The data shuffling implemented is: 


ANSWER (KEY(I)) = START (I), I = 1, 1024 


using long vector indexing. Hence the key long vector must contain values in the range 
1 — 1024, but the values need not be distinct. 


2 Specification 


SUBROUTINE M01 _INV_PERMUTE_LV_32(ANSWER , START , KEY) 
INTEGER*4 or REAL*4 ANSWER(,) , START(,) 
INTEGER*4 KEY (,) 


3 Description 


Local copies of the data and answer long vectors are made, and converted to vector mode. 
The keys are copied and changed to zero-based offsets, and converted to vector mode. Each 
row of this key vector set then contains an index of a row in the destination vector set. The 
data rows are processed in turn and the contents of the addressed row are copied to the 
(copy of the) destination vector set, indexed by the value in the same row position of the key 
row. This result vector set is then copied to the answer long vector and converted to matrix 
mode. 


© 4 References 


None 


5 Arguments 


ANSWER ~ INTEGER*4 or REAL*4 MATRIX 
On exit, ANSWER contains the shuffled version of the input matrix START. 


START — INTEGER*4 or REAL*¥4 MATRIX 
On entry, START should contain the data to be shuffled; START is unchanged on exit. 


KEY — INTEGER*4 MATRIX 


On entry, KEY should contain values in the range 1 — 1024 (not necessarily distinct) 
describing the required shuffle; KEY is unchanged on exit. 


6 Error Indicators 


None 


7 Auxiliary Routines 


The routine references routines Z.M01_PLV._CONV_ONLY and Z.M01_PLV_COPY_AND_CONV 
from the General Support library. 
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8 Accuracy 





Not applicable 


9 Further Comments 


Because of the way that the routine is coded, you should not assume that the start and key 
long vectors are processed with an index that increases in a simple way. 


10 Keywords 


Data movement, permutation, rearrange data, shuffle. 


11 Example 
The following FORTRAN-PLUS fragment reverses a long vector of integer values. 


ENTRY SUBROUTINE ENT 
INTEGER DATA(,), KEY(,), RESULT(,) 
DO 10 I = 1, 1024 
DATA(I) = 3 * I 
10 KEY(I) = 1025 -- I 
CALL MO1_PERMUTE_LV_32(RESULT, DATA, KEY) 
TRACE 1 (RESULT) 
RETURN 
END 





Results 


FORTRAN-PLUS Trace 
FORTRAN-PLUS Subroutine: ENT at Line 7 


Integer Matrix Local Variable RESULT in 32 bits -- addressed by Stack + 0.10 


(Row 01 Col 01) 3072, 2976, 2880, 2784, 
(Col 05) 2688, 2592, 2496, 2400, 
(Col 09) 2304, 2208, 2112, 2016, 
(Col 13) 1920, 1824, 1728, 1632, 
(Col 17) 1536, 1440, 1344, 1248, 
(Col 21) 1152, 1056, 960, 864, 
(Col 25) 768, 672, 576, . 480, 
(Col 29) 384, 288, 192, 96 
(Row 02 Col 01) 3069, 2973, 2877, 2781, 
(Col 05) 2685, 2589, 2493, 2397, 
(Col 09) 2301, 2205, 2109, 2013, 
(Col 13) 1917, 1821, 1725, 1629, 
(Col 17) 1533, 1437, 1341, 1245, 
(Col 21) - 1149, 1053, 957, 861, 
(Col 25) 765, 669, 573, 477, 
(Col 29) 381, 285, 189, 93 
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(Row 03 Col 01) 3066, 2970, 2874, 2778, 
(Col 05) 2682, 2586, 2490, 2394, 

(Col 09) 2298, 2202, 2106, 2010, 

(Col 13) 1914, 1818, 1722, 1626, 

(Col 17) 1530, 1434, 1338, 1242, 

(Col 21) 1146, 1050, . 954, 858, 

(Col 25) 762, 666, 570, 474, 

(Col 29) 378, 282, 186, 90 

(Row 30 Col 01) 2985, 2889, 2793, 2697, 
(Col 05) 2601, 2505, 2409, 2313, 

(Col 09) 2217, 2121, 2025, 1929, 

(Col 13) 1833, 1737, 1641, 1545, 

(Col 17) 1449, 1353, 1257, 1161, 

(Col 21) 1065, 969, 873, 777, 

(Col 25) 681, 585, 489, 393, 

(Col 29) 297, 201, 105, 9 

(Row 31 Col 01) 2982, 2886, 2790, 2694, 
(Col 05) 2598, 2502, 2406, 2310, 

(Col 09) 2214, 2118, 2022, 1926, 

(Col 13) 1830, 1734, 1638, 1542, 

(Col 17) - 1446, 1350, 1254, 1158, 

© (Col 21) 1062, 966, 870, 774, 
(Col 25) 678, 582, 486, 390, 

(Col 29) 294, 198, 102, 6 

(Row 32 Col 01) 2979, 2883, 2787, 2691, 
(Col 05) 2595, 2499, 2403, 2307, 

(Col 09) 2211, 2115, 2019, - 1923, 

(Col 13) 1827, 1731, 1635, 1539, 

(Col 17) 1443, 1347, 1251, 1155, 

(Col 21) 1059, 963, 867, 771, 

(Col 25) 675, 579, 483, 387, 

(Col 29) 291, 195, 99, 3 
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1 Purpose 
M01 _INV._PERMUTE-ROWS permutes the first M rows of a matrix according to a per- 
mutation vector (IV). The result is equivalent to the FORTRAN-PLUS statements: 


DO 10I1=1,M 
10 A PERMUTED (IV (I),) = A(I,) 


2 Specification 


SUBROUTINE M01_INV_PERMUTE_ROWS(A , AP, IV, N, M) 
INTEGER IV(),N,M 
<any type> A(,), AP(,) 


3 Description 


Rows are permuted according to the integer index vector IV such that row I is moved to row 


IV(I). 


4 References 


None 


5 Arguments 
A — <any type> MATRIX 


On entry, A should contain the matrix whose rows are to be permuted. A may be of any 
type and is unchanged on exit. 


AP - <any type> MATRIX 


On exit, AP contains the rows of A permuted according to the index vector IV. AP should 
usually be of the same type as A. If M is less than 32, rows M+1 to 32 are unchanged 
on exit. 


IV - INTEGER VECTOR 


On entry, IV should contain the required permutation; that is, row I of A will be moved 
to row IV(I) of AP. Elements 1 to M of IV must be in the range 1 to 32. If the entries of 
IV are not all distinct - for example, if IV(I) = IV(J) with J > I - then row AP(IV(J),) 
will have the value A(J,) on exit. IV is unchanged on exit. 





N - INTEGER 
On entry, N contains the number of planes in the matrix to be permuted; possible values 
for N are: 
N=1 for permuting a logical matrix 
N=8 for permuting a character matrix 
N = 8*n for permuting an INTEGER*n or REAL*n matrix 


N should be less than 257, and is unchanged on exit. 


M - INTEGER 
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11 


On entry M must contain a value in the range 1 to 32. Only the first M index values of 
IV are used. M is unchanged on exit. 


Error Indicators 


None 


Auxiliary Routines 
The routine references the General Support library routine Z.M01_AUX. 


Accuracy 
Not applicable 


Further Comments 
The parameters given as A and AP may be single arrays or part of a matrix set. For example, 
in: 


CALL M01 -INV-PERMUTE.COLS (L(,,5), LL(,, 10), IV, 1, 32) 


L and LL are logical matrix sets of size (at least) 5 and 10 respectively. 
You must not use a common block with the names of CZ _M01-HEX1F or CZ_M01_REVERSE. 


Keywords 


Permutation 


Example , 


The following FORTRAN-PLUS fragment reverses the order of the rows or a real matrix, 
that is AP = REVC(A) 


ENTRY SUBROUTINE ENT 
REAL A(,), AP(,) 
INTEGER IV() 

DO 10 I = 1, 32 


10 IV(I) = 33 - I 
DO 20 I = 1, 32 
DO 20 J=1, 32 


20 A(I,J) = FLOAT (I + J) 
CALL MO1_INV_PERMUTE_ROWS (A, AP, IV, 32, 32) 
TRACE 1 (AP) 
RETURN 
END 
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Results 


FORTRAN-PLUS Trace 


FORTRAN-PLUS Subroutine: 


ENT at Line i0 


M01 - Sorting 


Real Matrix Local Variable AP in 32 bits -- addressed by Stack + 0.10 


(Row 01 Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 

(Row 02 Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 

(Row 03 Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 


01) 
04) 
07) 
10) 
13) 
16) 
19) 
22) 
25) 
28) 
31) 
01) 
04) 
07) 
10) 
13) 
16) 
19) 
22) 
25) 
28) 
31) 
01) 
04) 
07) 
10) 
13) 
16) 
19) 
22) 
25) 
28) 
31) 


Aan nr P PP WWWAATUAAA PE FPF FWWWHA ATH SP Sf PW WwW WwW 


-3000000E+01, 3.4000000E+01, 
-6000000E+01, 3.7000000E+01, 
-9000000E+01, 4.0000000E+01, 
-2000000E+01, 4.3000000E+01, 
-5000000E+01, 4.6000000E+01, 
-8000000E+01, 4.9000000E+01, 
-1000000E+01, 5.2000000E+01, 
-4000000E+01, 5.5000000E+01, 
.7O000000E+01, 5.8000000E+01, 
-OOOOO00E+01, 6.1000000E+01, 
-3000000E+01, 6.4000000E+01 
-2000000E+01, 3.3000000E+01, 
-5000000E+01, 3.6000000E+01, 
-8000000E+01, 3.9000000E+01, 
- 1000000E+01, 4.2000000E+01, 
-4000000E+01, 4.5000000E+01, 
- TOOOO00E+01, 4.8000000E+01, 
-OOOOO0OE+01, 5.1000000E+01, 
-3000000E+01, 5.4000000E+01, 
-6000000E+01, 5.7000000E+01, 
-9000000E+01, 6.0000000E+01, 
-2000000E+01, 6.3000000E+01 
-1000000E+01, 3.2000000E+01, 
-4000000E+01, 3.5000000E+01, 
.7000000E+01, 3.8000000E+01, 
-OOOQOOOE+01, 4.1000000E+01, 
-3000000E+01, 4.4000000E+01, 
-6000000E+01, 4.7000000E+01, 
-9OO0000E+01, 5.Q0000000E+01, 
-2000000E+01, 5.3000000E+01, 
-5000000E+01, 5.6000000E+01, 
-8000000E+01, 5.9000000E+01, 
- 1000000E+01, 6.2000000E+01 
man010.02 


Annan Sf bP Sf WwW WwW Annan f& fP PW WwW 


anna PP fF PW WwW WwW 


- 5000000E+01, 
- 8000000E+01, 
. 1000000E+01, 
-4000000E+01, 
. TOOOOOOE+01, 
.0O00000E+01, 
. 3000000E+01, 
-6000000E+01, 
- 9000000E+01, 
. 2000000E+01, 


.4000000E+01, 
. 7000000E+01, 
.0000000E+01, 
. 3000000E+01, 
. 6000000E+01, 
.9000000E+01, 
.2000000E+01, 
.5000000E+01, 
.8000000E+01, 
. 1000000E+01, 


. 3000000E+01, 
-6000000E+01, 
- 9000000E+01, 
-2000000E+01, 
. 5000000E+01, 
- 8000000E+01, 
. 1000000E+01, 
-4000000E+01, 
- TOQOOOOOE+01, 
-Q000000E+01, 
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(Row 30 Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 

(Row 31 Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 

(Row 32 Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 


01) 
04) 
07) 
10) 
13) 
16) 
19) 
22) 
25) 
28) 


31) _ 


01) 
04) 
07) 
10) 
13) 
16) 
19) 
22) 
25) 
28) 
31) 
01) 
04) 
07) 
10) 
13) 
16) 
19) 
22) 
25) 
28) 
31) 
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-0000000E+00, 
-OOO0000E+00, 
.OO00000E+01, 
- 3000000E+01, 
-6000000E+01, 
. 9000000E+01, 
-2000000E+01, 
-5000000E+01, 
-8000000E+01, 
- 1000000E+01, 
-4000000E+01, 
-O000000E+00, 
. OO00000E+00, 
- OOQ00000E+00, 
. 2000000E+01, 
- 5000000E+01, 
- 8000000E+01, 
- 1000000E+01, 
-4000000E+01, 
. TOO0000E+01, 
-OOOO000E+01, 
. 3000000E+01, 
-O000000E+00, 
.O000000E+00, 
-QO000000E+00, 
- 1000000E+01, 
-4000000E+01, 
. TOOOOOOE+01, 
- OOOOO00E+01, 
-3000000E+01, 
-6000000E+01, 
-9000000E+01, 
. 2000000E+01, 


WWNNNFP RP RP OD WWWNHONNYP PRY NP WWNNYNNDNYDYP PY OD 
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- OOO0000E+00, 
- OO00000E+00, 
- 1O00000E+01, 
-4000000E+01, 
. TOOOOOOE+01, 
.OOO0000E+01, 
- 3000000E+01, 
-6000000E+01, 
- 9000000E+01, 
. 2000000E+01, 
- 5000000E+01 

. OOOO000E+00, 
-O000000E+00, 
- OQ0Q000E+01, 
- 3000000E+01, 
-6G000000E+01, 
- 9000000E+01, 
. 2000000E+01, 
- 5000000E+01, 
- 8000000E+01, 
. 1LO00000E+01, 
-4000000E+01 

- OOO0000E+00, 
-0000000E+00, 
-O000000E+00, 
. 2000000E+01, 
- 5000000E+01, 
- 8000000E+01, 
. LOOO000E+01, 
-4000000E+01, 
- TOOOOO0E+01, 
-OOOOO00E+01, 
- 3000000E+01 
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.0000000E+00, 
.OOOO000E+00, 
. 2000000E+01, 
- 5000000E+01, 
-8000000E+01, 
. LOOOOOOE+01, 
-4000000E+01, 
. TOOOOOOE+01, 
-OOOOO000E+01, 
. 3000000E+01, 


-0000000E+00, 
. OOOO000E+00, 
. 1000000E+01, 
-4000000E+01, 
. TOO0000E+01, 
-OOOOO0O0E+01, | 
. 3000000E+01, 
-6000000E+01, 
. 9000000E+01, 
. 2000000E+01, 


. QOOO000E+00, 
.0000000E+00, 
.0000000E+01, 
. 3000000E+01, 
-6000000E+01, 
- 9000000E+01, 
. 2000000E+01, 
. 5|000000E+01, 
. 8000000E+01, 
- 1000000E+01, 
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11.5 M01_.PERMUTE_COLS release 1 


1 Purpose 
M01.PERMUTE.COLS permutes the first M columns of a matrix according to a permu- 
tation vector(IV). The result is equivalent to the FORTRAN-PLUS statements: 


DO 101=1,M 
10 A.PERMUTED(,I) = A(,IV(D) 


2 Specification 


SUBROUTINE M01._.PERMUTE-_COLS(A , AP ,IV ,N ,M) 
INTEGER IV(),N,M 
<any type> A(,), AP(,) 


3 Description 


Columns are permuted according to the integer index vector IV, such that column IV(I) is 
moved to column I. 


4 References 


None 


5 Arguments 
A - <any type> MATRIX 


On entry, A contains the matrix whose columns are to be permuted. A may be of any 
type, and is unchanged on exit. 


AP ~ <any type> MATRIX 


On exit, AP contains the columns of A permuted according to the index vector IV. AP 
should usually be of the same type as A. If M is less than 32, columns M-+1 to 32 are 
unchanged on exit. 


IV - INTEGER VECTOR 


On entry, IV contains the required permutation, that is column IV(I) of A will be moved 
to column I of AP. Elements 1 to M of IV must be in the range 1 to 32 (but need not be 
distinct). IV is unchanged on exit. 


N - INTEGER 
On entry, N contains the number of planes in the matrix to be permuted; possible values 
for N are: 
N=1 for permuting a logical matrix 
N=8 for permuting a character matrix 
N = 8*n for permuting an INTEGER*n or REAL*n matrix 


N should be less than 257, and is unchanged on exit. 


M ~ INTEGER 


On entry M must contain a value in the range 1 to 32. Only the first M index values of 
IV are used; M is unchanged on exit. 
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10 
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Error Indicators 


None 


Auxiliary Routines 
The routine references the General Support library routine Z_M01_AUX. 


Accuracy 
Not applicable 


Further Comments 


The parameters given as A and AP may be single arrays or part of a matrix set. For example, 
in: 


CALL M01_-PERMUTE _COLS (L(, ,5), LL (,, 10), IV, 1, 32) 


L and LL are logical matrix sets of size (at least) 5 and 10 respectively. 
You must not use a common block with the name of CZ_M01_HEXIF. 


Keywords 


Permutation 


Example 


The following FORTRAN-PLUS fragment reverses the order of the columns of a real matrix, 
that is, AP = REVC(A). 


ENTRY SUBROUTINE ENT 
REAL AC(,), AP(,) 
INTEGER IV() 
bDO 10 I=1,32 

10 IV(I) = 33 - I 
DO 20 J=1, 32 
DO 20 T= 1, 32 

20 ACI,J) = FLOAT (I + J) 
CALL MO1_PERMUTE_COLS(A, AP, IV, 32, 32) 
TRACE 1 (AP) 
RETURN 
END 
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Results 


FORTRAN-PLUS Trace 


FORTRAN-PLUS Subroutine: 


Real Matrix 


(Row 01 Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 

(Row 02 Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 

(Row 03 Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
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Local Variable AP in 32 bits ~~ addressed by Stack + 0.10 


01) 


04) . 


07) 
10) 
13) 
16) 
19) 
22) 
25) 
28) 
31) 
01) 
04) 
07) 
10) 
13) 
16) 
19) 
22) 
25) 
28) 
31) 
01) 
04) 
07) 
10) 
13) 
16) 
19) 
22) 
25) 
28) 
31) 


OOrRrRRPRNNNN WW PNP RPP RPNYONN WWWHOkKR HF HF OND Ww WwW 


-3000000E+01, 3.2000000E+01, 
-QOOO000E+01, 2.9000000E+01, 
- TOOOOO0E+01, 2.6000000E+01, 
-4000000E+01, 2.3000000E+01, 
- 1000000E+01, 2.Q0000000E+01, 
-8000000E+01, 1.7000000E+01, 
-5000000E+01, 1.4000000E+01, 
-2000000E+01, 1.1000000E+01, 
-OOOO0000E+00, 8.0000000E+00, 
-OOOO000E+00, 5.0000000E+00, 
-OOOO0000E+00, 2.0000000E+00 
-4000000E+01, 3.3000000E+01, 
-1000000E+01, 3.0000000E+01, 
-8000000E+01, 2.7000000E+01, 
-5000000E+01, 2.4000000E+01, 
-2000000E+01, 2.1000000E+01, 
-9O00000E+01, 1.8000000E+01, 
-6OQ0000E+01, 1.5000000E+01, 
-3000000E+01, 1.2000000E+01, 
-OOOQ000E+01, 9.0000000E+00, 
-OOOO000E+00, 6.0000000E+00, 
-OOO0000E+00, 3.0000000E+00 
-5000000E+01, 3.4000000E+01, 
-2000000E+01, 3.1000000E+01, 
-9000000E+01, 2.8000000E+01, 
-6000000E+01, 2.5000000E+01, 
-3000000E+01, 2.2000000E+01, 
-OOOOOO0OE+01, 1.9000000E+01, 
. TOOOO000E+01, 1.6000000E+01, 
-4000000E+01, 1.3000000E+01, 
-1000000E+01, 1.0000000E+01, 
-QOOQ0000E+00, 7.0000000E+00, 
-OOQO0000E+00, 4.0000000E+00 
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OAor re ND W W 


. LOOOOOOE+01, 
- 8000000E+01, 
. 5000000E+01, 
.2000000E+01, 
. 9OOO000E+01, 
- 6000000E+01, 
. 3000000E+01, 
.OOO0000E+01, 
.OOOOO000E+00, 
. OOOOO000E+00, 


. 2000000E+01, 
- 9000000E+01, 
-6000000E+01, 
. 3000000E+01, 
.0O00000E+01, 
. TOOOOOOE+01, 
- 4000000E+01, 
. 1000000E+01, 
. OOOOOO00E+00, 
. 0000000E+00, 


. 3000000E+01, 
-OOOQO000E+01, 
. TOOOO000E+01, 
-4000000E+01, 
. LOOOOO0E+01, 
- 8000000E+01, 
- 5000000E+01, 
- 2000000E+01, 
-OO000000E+00, 
-QOOO000E+00, 
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(Row 30 Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 

(Row 31 Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 

(Row 32 Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 


01) 
04) 
07) 
10) 
13) 
16) 
19) 
22) 
25) 
28) 
31) 
01) 
04) 
07) 
10) 
13) 
16) 
19) 
22) 
25) 
28) 
31) 
01) 
04) 
07) 
10) 
13) 
16) 
19) 
22) 
25) 
28) 
31) 
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- 2000000E+01, 
- 9000000E+01, 
-6000000E+01, 
- 3000000E+01, 
- OOOO000E+01, 
- TOOOOO0E+01, 
-4000000E+01, 
- 1000000E+01, 
-8000000E+01, 
- 5000000E+01, 
- 2000000E+01, 
. 3000000E+01, 
- 0000000E+01, 
. TOOOOOOE+01, 
-4000000E+01, 
. LOOO000E+01, 
- 8000000E+01, 
- 5S000000E+01, 
- 2000000E+01, 
- 9000000E+01, 
- 6000000E+01, 
- 3000000E+01, 
-4000000E+01, 
- LOOO000E+01, 
- 8000000E+01, 
- 5S000000E+01, 
- 2000000E+01, 
- 9000000E+01, 
- 6000000E+01, 
. 3000000E+01, 
. OOOOO000E+01, 
. TOOOOOOE+01, 
- 4000000E+01, 


WOWW PSP PHTTHAHAWWW PEP KPH HT HWW Ww PPP POLO OT O 


. 1000000E+01, 
- 8000000E+01, 
- 5000000E+01, 
-2000000E+01, 
- 9000000E+01, 
-6000000E+01, 
- 3000000E+01, 
-OOOOO00E+01, 
. TOOOOOOE+01, 
-4000000E+01, 
. LOOOO00E+01 

. 2000000E+01, 
-9000000E+01, 
. 6(000000E+01, 
. 3000000E+01, 
. OOOOOO0E+01, 
. TOO0000E+01, 
-4000000E+01, 
- 1000000E+01, 
- 8000000E+01, 
- 5000000E+01, 
- 2000000E+01 

. 3000000E+01, 
- OOOO0000E+01, 
. TOOOOO0E+01, 
-4000000E+01, 
. 1OO0000E+01, 
-8000000E+01, 
- 5000000E+01, 
. 2000000E+01, 
- 9000000E+01, 
-6000000E+01, 
. 3000000E+01 
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.0000000E+01, 
.T000000E+01, 
.4000000E+01, 
. 1000000E+01, 
.8000000E+01, 
. BOOOOOOE+01, 
.2000000E+01, 
. 9000000E+01, 
.6000000E+01, 
.3000000E+01, 


. LOOO000E+01, 
- 8000000E+01, 
. 5000000E+01, 
. 2000000E+01, 
- 9000000E+01, 
-6000000E+01, 
. 3000000E+01, 
-OOOO0000E+01, 
. TOOOOOOE+01, 
-4000000E+01, 


.2000000E+01, 
. 9000000E+01, 
.6000000E+01, 
. 3000000E+01, 
.0000000E+01, 
. T000000E+01, 
.4000000E+01, 
. 1000000E+01, 
. 8000000E+01, 
. 5000000E+01, 
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Purpose 


M01.-PERMUTE-LV_32 permutes the values in a long vector of 4-byte values using an 
INTEGER*4 long vector key. The result is written to a new long vector and the original 
data is unaffected. The data shuffling implemented is: 


ANSWER (I) = START (KEY(I)), I= 1, 1024 


using long vector indexing. Hence the key long vector must contain values in the range 
1 — 1024, but the values need not be distinct. 


Specification 


SUBROUTINE M01_PERMUTE-LV_32(ANSWER , START , KEY) 
INTEGER*4 or REAL*4 ANSWER(,) , STAR T(, ) 
INTEGER*4 KEY (,) 


Description 


A local copy of the data is made, and converted to vector mode. The keys are copied and 
changed to zero-based offsets, then converted to vector mode. Each row of this key vector 
set then contains an index of a row in the data vector set. The key rows are processed in 
turn and the contents of the addressed row are copied to another vector set in the same row 
position as the key row. This result vector set is then copied to the answer long vector, and 
converted to matrix mode. 


References 
None 


Arguments 


ANSWER - INTEGER*4 or REAL*4 MATRIX 
On exit, ANSWER contains the shuffled version of the input matrix START. 


START - INTEGER*4 or REAL*4 MATRIX 
On entry, START should contain the data to be shuffled; START is unchanged on exit. 


KEY - INTEGER*4 MATRIX 
On entry, KEY should contain values in the range 1 — 1024 (not necessarily distinct) 
describing the required shuffle; KEY is unchanged on exit. 


Error Indicators 


None 


Auxiliary Routines 


This routine references routines Z. M01. PLV.CONV_ONLY and Z_ M01. PLV_COPY_AND._CONV 
from the General Support library. 


Accuracy 
Not applicable 
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9 Further Comments 


None 


10 Keywords 


Data movement, permutation, rearrange data, shuffle 


11 Example 
The following FORTRAN-PLUS fragment reverses a long vector of integer values. 


ENTRY SUBROUTINE ENT 
INTEGER DATA(,), KEY(,), RESULT(,) 
DO 10 I = 1, 1024 
DATA(I) = 3 * I 
10 KEY(I) = 1025 - I 
CALL MO1_PERMUTE_LV_32(RESULT, DATA, KEY) 
TRACE 1 (RESULT) 





RETURN 
END 


Results 


FORTRAN-PLUS Trace 


FORTRAN-PLUS Subroutine: ENT at Line 7 


Integer Matrix Local Variable RESULT in 32 bits -- addressed by Stack + 0.10 


(Row 01 Col 01) 3072, 2976, 2880, 2784, 
(Col 05) 2688, 2592, 2496, 2400, 
(Col 09) 2304, 2208, 2112, 2016, 
(Col 13) 1920, 1824, 1728, 1632, 
(Col 17) 1536, 1440, 1344, 1248, 
(Col 21) 1152, 1056, 960, 864, 
(Col 25) 768, 672, 576, 480, 
(Col 29) 384, 288, 192, 96 
(Row 02 Col 01) 3069, 2973, 2877, 2781, 
(Col 05) 2685, 2589, 2493, 2397, 
(Col 09) 2301, 2205, 2109, 2013, 
(Col 13) 1917, 1821, 1725, 1629, 
(Col 17) 1533, 1437, 1341, 1245, 
(Col 21) 1149, 1053, 957, 861, 
(Col 25) 765, 669, 573, 477, 
(Col 29) 381, 285, 189, 93 
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(Row 03 Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 


(Row 30 Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Row 31 Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Row 32 Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 


01) 
05) 
09) 
13) 
17) 
21) 
25) 
29) 


01) 
05) 
09) 
13) 
17) 
21) 
25) 
29) 
01) 
05) 
09) 
13) 
17) 
21) 
25) 
29) 
01) 
05) 
09) 
13) 
17) 
21) 
25) 
29) 


3066, 
2682, 
2298, 
i914, 
1530, 
1146, 

762, 

378, 


2985, 
2601, 
2517. 
1833, 
1449, 
1065, 

681, 

297, 


- 2982, 


2598, 
2214, 
1830, 
1446, 
1062, 

678, 

294, 
2979, 
2595, 
2211, 
1827, 
1443, 
1059, 

675, 

291, 


2970, 
2586, 
2202, 
1818, 
1434, 
1050, 

666, 

282, 


2889, 
2505, 
2121, 
1737, 
1353, 
969, 
585, 
201, 
2886, 
2502, 
2118, 
1734, 
1350, 
966, 
582, 
198, 
2883, 
2499, 
2115, 
1731, 
‘1347, 
963, 
579, 
195, 
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2793, 
2409, 
2025, 
1641, 
1257, 
873, 
489, 
105, 
2790, 
2406, 
2022, 
1638, 
1254, 
870, 
486, 
102, 
2787, 
2403, 
2019, 
1635, 
1251, 
867, 
483, 
99, 
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2697, 
2313, 
1929, 
1545, 
1161, 

TTT, 

393, 


2694, 
2310, 
1926, 
1542, 
1158, 

774, 

390, 


2691, 
2307, 
1923, 
1539, 
1155, 

771, 

387, 
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11.7 M01_PERMUTE_ROWS release 1 


1 Purpose 


M01_PERMUTE . ROWS permutes the first M rows of a matrix according to a permutation 
vector (IV). The result is equivalent to the FORTRAN-PLUS statements: 


DO 10I1=1,M 
10 10 ALPERMUTED(I,) = A (IV(I),) 


2 Specification 


SUBROUTINE M01_PERMUTE_.ROWS(A , AP ,IV,N ,M) 
INTEGERIV(),N,M 
<any type> A(,) ’ AP (,) 


3 Description 


Rows are permuted according to the integer index vector IV such that row IV(I) is moved 
to row I. 


4 References 
None 


5 Arguments 
A -— <any type> MATRIX 


On entry, A should contain the matrix whose rows are to be permuted. A may be of any 
type and is unchanged on exit. 


AP - <any type> MATRIX 


On exit, AP contains the rows of A permuted according to the index vector IV. AP should 
usually be of the same type as A. If M is less than 32, rows M+1 to 32 are unchanged 
on exit. 


IV - INTEGER VECTOR 


On entry, IV should contain the required permutation; that is, row I of A will be moved 
to row IV(I) of AP. Elements 1 to M of IV must be in the range 1 to 32. If the entries of 
IV are not all distinct — for example, if IV(I) = IV(J) with J > I - then row AP (IV(J), ) 
will have the value A(J,) on exit. IV is unchanged on exit. 


N - INTEGER 
On entry, N contains the number of planes in the matrix to be permuted; possible values 
for N are: 
N=1 for permuting a logical matrix 
N=8 for permuting a character matrix 
N = 8*n for permuting an INTEGER*n or REAL*n matrix 


N should be less than 257, and is unchanged on exit. 
M - INTEGER 


On entry M must contain a value in the range 1 to 32. Only the first M index values of 
IV are used. M is unchanged on exit. 
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6 Error Indicators 





None 


7 Auxiliary Routines 
The routine references the General Support library routine Z_M01_ AUX. 


8 Accuracy 
Not applicable 


9 Further Comments 
The parameter given as A and AP may be single arrays or part of a matrix set. For example, 
in: 


CALL M01 .PERMUTE - ROWS (L(, ,5),LL(,, 10), IV, 1,32) 


L and LL are logical matrix sets of size (at least) 5 and 10 respectively. 
You must not use common blocks with name CZ.M01_HEXI1F. 


10 Keywords 


Permutation 


11 Example 


The following FORTRAN-PLUS fragment given reverses the order of the rows of a real 
matrix that is, AP = REVC(A). 





ENTRY SUBROUTINE ENT 
REAL A(,), AP (,) 
INTEGER IV() 
DO'10 I = 1,32 
10 IV (I) = 33 - I 
DO 20 I= 1, 32 
DO 20 J=1, 32 
20 A(I,J) = FLOAT(I + J) 
CALL MO1_PERMUTE_ROWS (A, AP, IV, 32, 32) 
TRACE 1 (AP) 
RETURN 
END 
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Results 





FORTRAN-PLUS Trace 
FORTRAN-PLUS Subroutine: ENT at Line 10 


Real Matrix Local Variable AP in 32 bits -- addressed by Stack + 0.10 


(Row 01 Col 01) 3.3000000E+01, 3.4000000E+01, 3.5000000E+01, 
(Col 04) 3.6000000E+01, 3.7000000E+01, 3.8000000E+01, 
(Col 07) 3.9000000E+01, 4.0000000E+01, 4.1000000E+01, 
(Col 10) 4.2000000E+01, 4.3000000E+01, 4.4000000E+01, 
(Col 13) 4.5000000E+01, 4.6000000E+01, 4.7000000E+01, 
(Col 16) 4.8000000E+01, 4.9000000E+01, 5.0000000E+01, 
(Col 19) 5.1000000E+01, 5.2000000E+01, 5.3000000E+01, 
(Col 22) 5.4000000E+01, 5.5000000E+01, 5.6000000E+01, 
(Col 25) 5.7000000E+01, 5.8000000E+01, 5.9000000E+01, 
(Col 28) 6.0000000E+01, 6.1000000E+01, 6.2000000E+01, 
(Col 31) 6.3000000E+01, 6.4000000E+01 
(Row 02 Col 01) 3.2000000E+01, 3.3000000E+01, 3.4000000E+01, 
(Col 04) 3.5000000E+01, 3.6000000E+01, 3.7000000E+01, 
(Col 07) 3.8000000E+01, 3.9000000E+01, 4.0000000E+01, 
(Col 10) 4.1000000E+01, 4.2000000E+01, 4.3000000E+01, 
(Col 13) 4.4000000E+01, 4.5000000E+01, 4.6000000E+01, 
(Col 16) 4.7000000E+01, 4.8000000E+01, 4.9000000E+01, 
(Col 19) 5.0000000E+01, 5.1000000E+01, 5.2000000E+01, 
© (Col 22) 5.3000000E#01, 5.4000000E+01, 5.5000000E+01, 
(Col 25) §5.6000000E+01, 5.7000000E+01, 5.8000000E+01, 
(Col 28) 5.9000000E+01, 6.0000000E+01, 6.1000000E+01, 
(Col 31) 6.2000000E+01, 6.3000000E+01 
(Row 03 Col 01) 3.1000000E+01, 3.2000000E+01, 3.3000000E+01, 
(Col 04) 3.4000000E+01, 3.5000000E+01, 3.6000000E+01, 
(Col 07) 3.7000000E+01, 3.8000000E+01, 3.9000000E+01, 
(Col 10) 4.0000000E+01, 4.1000000E+01, 4.2000000E+01, 
(Col 13) 4.3000000E+01, 4.4000000E+01, 4.5000000E+01, 
(Col 16) 4.6000000E+01, 4.7000000E+01, 4.8000000E+01, 
(Col 19) 4.9000000E+01, 5.0000000E+01, 5.1000000E+01, 
(Col 22) 5.2000000E+01, 5.3000000E+01, 5.4000000E+01, 
(Col 25) §.5000000E+01, 5.6000000E+01, 5.7000000E+01, 
(Col 28) 5.8000000E+01, 5.9000000E+01, 6.0000000E+01, 
(Col 31) 6.1000000E+01, 6.2000000E+01 
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(Row 30 Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 
(Col 

(Row 31 Col 
(Col 
(Col 
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(Col 
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(Row 32 Col 
(Col 
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(Col 
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01) 
04) 
07) 
10) 
13) 
16) 
19) 
22) 
25) 
28) 
31) 
01) 
04) 
07) 
10) 
13) 
16) 
19) 
22) 
25) 
28) 
31) 
01) 
04) 
07) 
10) 
13) 
16) 
19) 
22) 
25) 
28) 
31) 


WNHNNNFPRPOWOATINWWNNNHKF REPO DWWWNNNKH BH eB AD 


-O000000E+00, 5.0000000E+00, 
-OO0O00000E+00, 8.0000000E+00, 
-OOOOOOOE+01, 1.1000000E+01, 
-3000000E+01, 1.4000000E+01, 
-6000000E+01, 1.7000000E+01, 
-9000000E+01, 2.0000000E+01, 
-2000000E+01, 2.3000000E+01, 
-5000000E+01, 2.6000000E+01, 
-8000000E+01, 2.9000000E+01, 
- 1000000E+01, 3.2000000E+01, 
-4000000E+01, 3.5000000E+01 
-O000000E+00, 4.0000000E+00, 
-QO00000E+00, 7.0000000E+00, 
-OO0Q0000E+00, 1.0000000E+01, 
-2000000E+01, 1.3000000E+01, 
-5000000E+01, 1.6000000E+01, 
-8000000E+01, 1.9000000E+01, 
-1000000E+01, 2.2000000E+01, 
-4000000E+01, 2.5000000E+01, 
. TO00000E+01, 2.8000000E+01, 
-OOOOOOOE+01, 3.1000000E+01, 
-3000000E+01, 3.4000000E+01 
-OOQ0000E+00, 3.0000000E+00, 
-QOOO0000E+00, 6.0000000E+00, 
-OOOQO000E+00, 9.0000000E+00, 
-1000000E+01, 1.2000000E+01, 
-4000000E+01, 1.5000000E+01, 
- TOOOOO0E+01, 1.8000000E+01, 
-OOOOOO0E+01, 2.1000000E+01, 
-3000000E+01, 2.4000000E+01, 
-6000000E+01, 2.7000000E+01, 
-9000000E+01, 3.0000000E+01, 
-2000000E+01, 3.3000000E+01 
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.OOOOO000E+00, 
.OOOOOO0E+00, 
. 2000000E+01, 
. 5S000000E+01, 
-8000000E+01, 
. LOOOOO0E+01, 
- 4000000E+01, 
. TOOO000E+01, 
-OOOOO00E+01, 
. 3000000E+01, 


. 0000000E+00, 
.0000000E+00, 
. 1000000E+01, 
.4000000E+01, 
. TOOO000E+01, 
. 0000000E+01, 
. 3000000E+01, 
. 6000000E+01, 
.9000000E+01, 
. 2000000E+01, 


. OOOOOO0E+00, 
. OOOO0000E+00, 
.QO00000E+01, 
- 3000000E+01, 
-6000000E+01, 
- 9000000E+01, 
. 2000000E+01, 
- 5000000E+01, 
- 8000000E+01, 
. 1000000E+01, 
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11.8 M01_SORT_V_I4 release 1 





1 Purpose 


M01 .SORT_V_I4 sorts the first N elements of an integer vector into ascending or descending 
order. The permutation required to perform the sort is returned to the calling routine. 


2 Specification 


SUBROUTINE M01_SORT_V_I4 (IV , N, UP , PERM , IFAIL) 
INTEGER *1 PERM() 

INTEGER IV() , N , IFAIL 

LOGICAL UP 


3 Description 


The sort is carried out by spreading the vector, IV, across the DAP and counting the number 
of elements less than or equal to each particular element. Comparing this count with an index 
vector and selecting the relevant element from each column of the DAP completes the sort 
when all elements of IV are distinct. If there are repeated elements in IV, a logy duplication 
process is carried out to regenerate the multiple values. 


4 References 
None 


5 Arguments 
@ IV - INTEGER VECTOR 


On entry, components 1 to N of IV contain the elements to be sorted. On exit, compo- 
nents 1 to N will have been sorted as required. Elements N+1 to 32 are unchanged on 
exit. 


N - INTEGER 


On entry, N specifies how many components of IV are to be sorted. N must lie in the 
range 1 to 32, and is unchanged on exit. 


UP - LOGICAL 
If UP is .TRUE. on entry, then IV is sorted into ascending order, otherwise IV is sorted 
into descending order. UP is unchanged on exit. 

PERM - INTEGER *1 VECTOR 


On exit, PERM contains the permutation required to perform the sort, that is, the sort 
was equivalent to: 


DO 10I=1,N 
10 JV(I) = IV(PERM(I)) 
Elements N+1 to 32 of PERM are zero on exit. 
IFAIL —- INTEGER 


Unless the routine detects an error (see Error Indicators below) IFAIL contains zero 
on exit. 
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6 Error Indicators 
Errors detected by the routine: 
IFAIL = 1 N is not in the range 1 to 32 





7 Auxiliary Routines 


The routine calls the General Support library routines X05. NORTH _ BOUNDARY, X05. PATTERN 
and X05.SHORT_INDEX. 


8 Accuracy 
Not applicable 


9 Further Comments 
None 


10 Keywords 
Sorting 


11 Example 


The vector to be sorted consists of the numbers 1 to 8, each repeated 4 times. The vector is 
sorted into ascending order. ° 


Host program 
INTEGER IV(32), PERM(32) 


COMMON /VEC1/IV /VEC2/PERM 
COMMON /SCALAR/N,IFAIL 





N = 32 
DO 10 T= 1, 32 
10 IV(I) = MOD(I-1, 8) +1 


CALL DAPCON(’ent.dd’) 
CALL DAPSEN(’SCALAR? ,N,1) 
CALL DAPSEN(’VEC1’ ,IV,32) 


CALL DAPENT(’ ENT? ) 


CALL DAPREC(’SCALAR? ,N, 2) 
CALL DAPREC(’VEC1? ,IV,32) 
CALL DAPREC(’VEC2’ , PERM, 32) 


CALL DAPREL 


WRITE (6, 100) IFAIL, (IV(I), I = 1,32) 
100 FORMAT (’?IFAIL = ’, I1, //, ’SORTED DATA’, //, (4I5)) 
WRITE (6,200) (PERM(I), I = 1,32) 
200 FORMAT (/,’PERMUTATION’, //, (4I5)) 
STOP 
END 
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DAP program 


ENTRY SUBROUTINE ENT 


INTEGER IV(), PERM4() 
INTEGER *1 PERM() 

COMMON /VEC1/IV /VEC2/PERM4 
COMMON /SCALAR/N,IFAIL 


CALL CONVFSI(N, 1) 
CALL CONVFVICIV,32,1) 


CALL MO1_SORT_V_I4(IV,N, .TRUE., PERM, IFAIL) 
PERM4 = PERM 
CALL CONVVFICIV,32,1) . 


CALL CONVVFI(PERM4 , 32,1) 
CALL CONVSFI(N, 2) 


RETURN 
END 

Results 

IFAIL = 0 

SORTED DATA 
1 1 1 1 
2 2 2 2 
3 3 3 3 
4 4 4 4 
5 5 5 5 
6 6 6 6 
7 7 7 7 
8 8 8 8 

PERMUTATION 
1 1 1 1 
2 2 2 2 
3 3 3 3 
4 4 4 4 
5 5 5 5 
6 6 6 6 
7 7 7 7 
8 8 8 8 
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Purpose 


M01-SORT_V_R4 sorts the first N elements of a real vector into ascending or descending 
order. The permutation required to perform the sort is returned to the calling routine. 


Specification 


SUBROUTINE M01_SORT_V_R4(RV , N , UP , PERM , IFAIL) 
INTEGER *1 PERM () 

INTEGER N , IFAIL 

REAL RV() 

LOGICAL UP 


Description 


The sort. is carried out by spreading the vector RV across the DAP, and counting the number - 
of elements less than or equal to each particular element; comparing this with an index vector 
and selecting the relevant element from each column of the DAP completes the sort when all 
elements of RV are distinct. If there are repeated elements in RV, a logy duplication process 
is carried out to regenerate the multiple values. 


‘References 


None 


Arguments 
RV —- REAL VECTOR 


On entry, components 1 to N of RV contain the elements to be sorted. On exit, compo- 
nents 1 to N will have been sorted as required. Elements N+1 to 32 are unchanged on 
exit. 


N ~ INTEGER 


On entry N specifies how many components of RV are to be sorted. N must lie in the 
range 1 to 32, and is unchanged on exit. 


UP - LOGICAL 
If UP is .TRUE. on entry, then RV is sorted into ascending order, otherwise RV is sorted 
into descending order. UP is unchanged on exit. 

PERM - INTEGER *1 VECTOR 


On exit PERM contains the permutation required to perform the sort, that is, the sort 
was equivalent to: 


DO 10I=1,N 
10 SV(I) = RV(PERM (1)) 
Elements N+1 to 32 of PERM are zero on exit. 
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5 Arguments - continued 
IFAIL - INTEGER 


Unless the routine detects an error (see Error Indicators below) IFAIL contains zero 
on exit. 





6 Error Indicators 
Errors detected by the routine: 
IFAIL = 1 N is not in the range 1 to 32 


7 Auxiliary Routines 


The routine calls the General Support library routines X05. NORTH . BOUNDARY, X05_ PATTERN 
and X05.SHORT_INDEX. 


8 Accuracy 
Not applicable 


9 Further Comments 
None 


10 Keywords 
Sorting 


© ‘11 Example 


The vector to be sorted consists of the numbers 1.0 to 8.0, each repeated 4 times. The vector 
is sorted into ascending order. 


Host program 


INTEGER PERM (32) 

REAL RV(32) 

COMMON /VEC1/RV /VEC2/PERM 
COMMON /SCALAR/N,IFAIL 


N = 32 
DO 10 I = 1,32 
10 RV(I) = MOD(I-1,8)+1 


CALL DAPCON(’ ent.dd’) 
CALL DAPSEN(’SCALAR? ,N,1) 
CALL DAPSEN(’VEC1? ,RV,32) 


CALL DAPENT(’ENT?) 
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CALL DAPREC(’SCALAR’ ,N,2) 
CALL DAPREC(’VEC1? ,RV,32) 
CALL DAPREC(’VEC2? , PERM, 32) 





CALL DAPREL 


WRITE (6, 100) IFAIL, (RV(I), I = 1,32) 
100 FORMAT (?IFAIL = *, Ii, //, ’SORTED DATA’, //, (4F5.0)) 
WRITE (6,200) (PERM(I), I = 1,32) 
200 FORMAT (/,’PERMUTATION’, //, (415)) 
STOP 
END 


DAP program 


ENTRY SUBROUTINE ENT 


INTEGER PERM4() 

INTEGER *1 PERM () 

REAL RV() 

COMMON /VEC1/RV /VEC2/PERM4 
COMMON /SCALAR/ N,IFAIL 


CALL CONVFSI(N, 1) 
CALL CONVFVE(RV,32,1) 





CALL MO1_SORT_V_R4(RV, N, .TRUE., PERM, IFAIL) 
PERM4 = PERM 

CALL CONVVFE(RV, 32, 1) 

CALL CONVVFI(PERM4, 32, 1) 

CALL CONVSFI(N, 2) 


RETURN 
END 
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Results 

IFAIL = 0 

SORTED DATA 
1. 1 1. 1. 
2. 2 2. 2. 
3. 3 3. 3. 
4. 4 4. 4. 
5. 5 5. 5. 
6. 6 6. 6. 
7. 7 7. 7. 
8. 8 8. 8. 

PERMUTATION 
1 1 1 1 
2 2 2 2 
3 3 3 3 
4 4 4 4 
5 5 § 5 
6 6 6 6 
7 7 7 7 
8 8 8 8 
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12.1 S04. ARC_COS S — Special functions 


12.1 S04_ ARC_COS release 1 


1 Purpose 


S04. ARC_COS returns the value of the inverse cosine function arccos (x) for a matrix argu- 
ment. The result lies in the range (0, z]. 


2 Specification 


REAL MATRIX FUNCTION S04. ARC_COS(X , EMASK) 
REAL X (,) 
LOGICAL EMASK (,) 


3 Description 


Arccos is approximated using a Tschebyshev polynomial expansion of the form: 


arcsin(z) ~ p(x) =a y_ ar T;(t) where ¢=4z?~1 


f 


where > is a series equal, term for term, to ye except that the first term in ye is half 
the first term in ys. 


The approximation for different values of the argument z is as follows: 


arccos(z) ~/2—p(xz) for 2 € [—1/V2, 1/V2) 
arccos(z) ~ t—p(/1 — 2?) for « € [-1, -1/72) 
arccos(z) ~p(Vl—2?) for 2€(1/V2, 1] 


For |z| > 1 the result is undefined. 


4 References 
[1] ABRAMOWITZ M and STEGUNI A 


Handbook of Mathematical Functions; chapter 4 section 4, p 79: Dover Publications 
1968. 


[2] FOX L and PARKER I 
Chebyshev Polynomials in Numerical Analysis: Oxford University Press; 1968. 


5 Arguments 
X ~ REAL MATRIX 


On entry, X contains the points at which the evaluation of arccos is required. All elements 
of X must be defined on entry. X is unchanged on exit. 


EMASK - LOGICAL MATRIX 


On exit, EMASK is set . TRUE. at positions corresponding to invalid arguments (see 
Error Indicators below). 
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6 Error Indicators 


Arccos(z) is undefined for |x| > 1. The routine returns zero for any such arguments and 
the corresponding bit in EMASK is set .TRUE. 


a 7 Auxiliary Routines 
None 


8 Accuracy 


i The accuracy is better than 20 parts in 10’ except for |z| very close to unity, when only 3 
“4 or 4 significant figures can be guaranteed. 


9 Further Comments 
None 


a 10 Keywords 


Arccosine, special function 
11 Example 


The example calculates arccos (x) for 1024 values of x between —1 and 1. 


© Host program 
ae 
fe 

2 3 


PROGRAM MAIN 
REAL X(1024), Y(1024) 
COMMON /XY/X,Y 
Cc 
4 C Initialise data for testing function 
“sgeg’ c 
DO iI = 1,1024 
X (I) = FLOAT(I-1)*2.0 / 1023.0 -1.0 


1 CONTINUE 
Cc 


C Connect to DAP module 
Cc 


CALL DAPCON(? ent.dd’) 
Cc 


C Send testdata to the DAP 
Cc 


CALL DAPSEN(? XY’ ,X, 1024) 
c 


C Call the DAP ENTRY subroutine 
Cc 


CALL DAPENT(?ENT? ) 
Cc 


C Retrieve data and results from the DAP 
Cc 





CALL DAPREC(’XY’ ,X, 2048) 
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c 
C Release the DAP 
Cc 
CALL DAPREL 
Cc 
C Write out a sample selection of the data and results for inspection 
c 


WRITE (6,2) 
2 FORMAT(6X, ’X’, 11X,’Arccos(X)’/) 
DO 3 I = 1,1024,32 
3 WRITE (6,4) X (I), Y(I) 
4  FORMAT(1X,2G15.7) 
STOP 
END 


DAP program 


ENTRY SUBROUTINE ENT 
REAL X(,), Y(,) 
LOGICAL EMASK (,) 
COMMON /XY/X,Y 





c 
C Note the EXTERNAL statement for this function 
C : 

EXTERNAL REAL MATRIX FUNCTION_SO4_ARC_COS 
Cc 
C Convert input data 
c 

CALL CONVFME(X) 

Y = S04_ARC_COS(X,EMASK) 

IF (ANYCEMASK)) TRACE 1 (EMASK) 
C 
C Convert input data and results back to host format 
Cc 


CALL CONVMFE(X) 
CALL CONVMFE(Y) 
RETURN 

END 
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Results 


x 


-1.0000000 
- 9374389 
8748778 
. 8123167 
-. 7497556 
6871945 
. 6246334 
. 5620723 
4995112 
- 4369501 
. 3743891 
. 3118280 
. 2492669 
. 1867058 
. 1241447 
-6158358e-01 
.9775162e-03 
-6353867e-01 
. 1260997 
. 1886609 
. 2612219 
. 3137830 
. 3763441 
- 4389052 
.5014663 
- 5640274 
. 6265885 
6891496 
. 7517107 
. 8142718 
- 8768328 
- 9393940 
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ccos(X) 


. 141593 
. 785996 
- 635980 
-518910 
- 418489 
. 328417 
. 245458 
. 167686 
- 093831 
- 023001 
-954534 
- 887913 
. 822720 
. 758604 
695262 
. 632419 
. 569818 
507215 
- 444360 
. 380998 
- 316854 
. 251621 
. 184949 
116416 
.045503 


.9715414 
- 8936281 
8104811 
. 7201442 
- 6193231 
-5015618 
- 3499371 
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12.2 S04_ARC_ SIN - release 1 


1 Purpose 


152 


$04. ARC_SIN returns the value of the inverse sine function arcsin(z) for a matrix argument. 
The result lies in the range [—7/2, 7/2]. 


Specification 


REAL MATRIX FUNCTION S04. ARC_SIN (X , EMASK) 
REAL X(,) 
LOGICAL EMASK (,) 


Description 


Arcsin is approximated using a Tschebyshev polynomial expansion. Since arcsin(—2) = 
—arcsin(z) it is only necessary to consider positive arguments. In the evaluation of arcsin, 
an expansion is used of the form: 

i 


p(z)= & > ax To(t) where t= 427-1 


where >> is a series equal, term for term, to a except that the first term in is half 
the first term in De 


The approximation for different value of the argument z is as follows: 


arcsin(z)~ p(x) where z € (0, 1/V2] 


arcsin(z) ~ 7/2—p(\/1— 2?) where 2 €(1/V2,1] 


For |z| > 1 the result is undefined. 


References 
[1] ABRAMOWITZ M and STEGUNIA 


Handbook of Mathematical Functions; chapter 4 section 4, p 79: Dover Publications 
1968. 


[2] FOX L and PARKER I 
Chebyshev Polynomials in Numerical Analysis: Oxford University Press, 1968. 


Arguments 
X - REAL MATRIX 


On entry, X contains the points at which the evaluation of arccos is required. All elements 
of X must be defined on entry. X is unchanged on exit. 


EMASK ~ LOGICAL MATRIX 


On exit, EMASK is set .TRUE. at positions corresponding to invalid arguments (see 
Error Indicators below). 
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Error Indicators 


Arccos (2) is undefined for |x| > 1. The routine returns zero for any such arguments and the 
corresponding bit in EMASK is set .TRUE. 


Auxiliary Routines 


None 


Accuracy 


The accuracy is better than 20 parts in 10’ except for |z| very close to unity, when only 3 
or 4 significant figures can be guaranteed. 


Further Comments 


None 


Keywords 


Arccosine, special function 


Example 


The example calculates arcsin (x) for 1024 values of z between —1 and 1. 


Host program 


PROGRAM MAIN : 
REAL X(1024) , Y(1024) 
COMMON /XY/X,Y 
Cc 
C Initialise data for testing function 
Cc 
DO iI = 1,1024 
X(I) = FLOAT (I-1)*2.0/1023.0 - 1.0 
1 CONTINUE 


Cc 
C Connect to DAP module 
Cc 
CALL DAPCON(’ ent.dd?’) 
Cc 
C Send testdata to the DAP 
Cc 
CALL DAPSEN(’XY’ ,X, 1024) 
Cc 
C Call the DAP ENTRY subroutine 
Cc 
CALL DAPENT(’ ENT?) 
C . 
C Retrieve data and results from the DAP 
Cc 


CALL DAPREC(?XY’,X, 2048) 
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Cc 
C Release the DAP 
Cc 
CALL DAPREL 
Cc 
C Write out a sample selection of the data and results for inspection. 
C 


WRITE (6,2) 
2 FORMAT(6X,’X’?,11X, ’Arcsin(X)?/) 
DO 3 I = 1,1024,32 
3 WRITE (6,4) X(I),Y(I) 
4 FORMAT (1X, 2615.7) 
STOP 
END 


DAP program 


ENTRY SUBROUTINE ENT 
REAL X(,),Y(,) 
LOGICAL EMASK(, ) 
COMMON /XY/X,Y 





Cc 
C Note the EXTERNAL statement for this function 
Cc 

EXTERNAL REAL MATRIX FUNCTION SO4_ARC_SIN 
Cc 
C Convert input data 
Cc 

CALL CONVFME(X) 

Y = S04_ARC_SIN(X, EMASK) 

IF (ANY(EMASK)) TRACE 1 (EMASK) 
Cc 
C Convert input data and results back to host format 
C 


CALL CONVMFE(X) 
CALL CONVMFE(Y) 
RETURN 

END 
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Results 

x Arcsin(X) 
~1.0000000 ~1.570796 
-.9374389 -1.215199 
-.8748778 -1.065183 
~.8123167 -.9481134 
-.7497556 -.8476925 
~.6871945 -. 7576209 
-.6246334 -.6746613 
-. 5620723 -. 5968893 
-.4995112 ~.5230349 
-.4369501 -.4522050 
~.3743891 ~.3837375 
~.3118280 -.3171163 
-.2492669 -.2519231 
~.1867058 -.1878080 
-.1241447 -.1244658 


-6158358e-01 -6162257e-01 
.9775162e-03 .9775162e-03 
-6353867e-01 -6358147e-01 


.1260997 1264364 
.1886609 .1897984 
2512219 2539426 
© .3137830 .3191746 
.3763441 .3858470 
.4389052 .4543798 
.5014663 . 5252929 
.5640274 .5992549 
6265885 .6771679 
.6891496 . 7603152 
.7517107 .8506517 
8142718 9514732 
.8768328 1.069234 
.9393940 1.220859 
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12.3 S04_ ATAN2_M release 1 


1 Purpose 


156 


$04. ATAN2_M is a matrix function similar to the standard FORTRAN ATAN2 function. 
It returns a matrix of values in the range —7 to m for arc-tangent(matrix-1/matrix-2), in the 
correct quadrant, and with divide-by-zero errors avoided. If both arguments are zero, zero 
is returned. 


Specification 


REAL MATRIX FUNCTION S04. ATAN2_M (A , B) 
REAL A(,) 3 B(,) 


Description 


A logical mask is set up, where each element is defined by the relative magnitudes of the 
arguments to ATAN2_M. Where the absolute value of an element of matrix A is greater than 
that of B, the logical mask element is set to .TRUE.; for all other cases the logical mask 
element is set to FALSE. 


ATAN2_M takes the value: 





ABS(B) ee ; 
ATAN (Fx) where ABS(A) > ABS(B) (the logical mask is .TRUE.) 
ABS(A) , 
a /2—ATAN ABS(B) where ABS(A) < ABS(B) (the logical mask is .FALSE.) 


Thus the built-in ATAN function is always presented with arguments whose values are in 
the range zero to one, and divide-by-zero errors are avoided, except when the corresponding 
elements in each argument are zero. After the ATAN operation, the results are corrected 
to put their values into the correct quadrants, from —7 to 7, according to the signs of the 
arguments. 


References 


None 


Arguments 
A ~ REAL MATRIX 


On entry, A contains values proportional to the sines of the angles to be returned by the 
function, and is unchanged on exit. 


B - REAL MATRIX 


On entry, B contains values proportional to the cosines of the angles to be returned by 
the function, and is unchanged on exit. 


Error Indicators 


None 


man010.02 AMT 

















S - Special functions 12.3 S04. ATAN2_M 


7 


10 


11 


Auxiliary Routines 


None 


Accuracy 


Over most of the range the results are accurate to within one part in 10°. Under worst case 
conditions, where the resultant angle is 7/4, 3/4, and so on, the error may approach two 
parts in 10°. 


Further Comments 


A program interrupt will occur if corresponding elements of A and B are both zero. 


Keywords 


Arc-tangent, inverse tangent 


Example 


In the following example the host routine sets up array ANGLES to contain the radian 
equivalents of 0, 0.1, 0.2 ... degrees. The DAP routine calculates the sines and cosines of 
these angles, and then calls S04.ATAN2_M to return the original angles. In this example 
ANGLES is treated as a long vector. 


Host program 


PROGRAM MATTESTHOST 
REAL ANGLES(1024) 


COMMON/DAP/ ANGLES 
Cc 
C Conversion factor from degrees to radians 
Cc 
F=3.14159265/180.0 
Cc 
C Initialise data for testing function 
Cc 


DO 1 J=1,1024 
1 ANGLES (J)=FLOAT(J-1)*F*0.1 


( Connect to DAP module 

° CALL DAPCON( mattest.dd’) 

; Send testdata to the DAP 

: CALL DAPSEN(?DAP? , ANGLES, 1024) 
: Call the DAP ENTRY subroutine 

: CALL DAPENT(?MATTESTDAP’ ) 

: Retrieve the results from the DAP 
c 
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CALL DAPREC(’DAP?’ , ANGLES , 1024) 





c 
C Release the DAP 
c 
CALL DAPREL 
Cc 
C Write out a sample selection of the data and results for inspection 
c 


WRITE(6,2)(J,ANGLES(J) , J=1,1024,32) 
2 FORMAT(4(’ 7,14,’ °,F9.6)) 

STOP 

END 


DAP program 


ENTRY SUBROUTINE MATTESTDAP 
REAL*4 SINVALS(,) ,COSVALS(, ) , ANGLES(, ) 
COMMON/DAP/ANGLES 

c 


Q 


Note the EXTERNAL statement for this function 


EXTERNAL REAL*4 MATRIX FUNCTION SO04_ATAN2_M 


Q 


Convert input data 





Cc 
CALL CONVFME (ANGLES) 
Cc 
C Calculate sine and cosine components 
c 
SINVALS=SIN (ANGLES) 
COSVALS=COS (ANGLES) 
ANGLES=S04_ATAN2_M(SINVALS , COSVALS) 
c 
C Convert input results back to host format 
Cc 
CALL CONVMFE(ANGLES) 
RETURN 
END 
Results 


1 -000000 33 055851 65 .111701 97 . 167552 
129 223402 161 279253 193 .335103 225 . 390954 
257 -446804 289 -502655 321 558506 353 -614356 
385 -670206 417 726058 449 .781908 481 -837757 


513 -893608 545 -949459 577 1.005308 609 1.061160 
641 1.117010 673 1.172861 705 1.228711 737 1.284562 
769 1.340412 801 1.396263 833 1.452113 865 1.507964 
897 1.563814 929 1.619666 961 1.675517 993 1.731367 
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1 Purpose 


S04_ ATAN2.V is a vector function similar to the standard FORTRAN ATAN2 function. It 
returns a vector of values in the range —7 to m for arc-tangent(vector-1/vector-2), in the 
correct quadrant, and with divide-by-zero errors avoided. If both arguments are zero, zero 
is returned. , ; 


2 Specification 


REAL VECTOR FUNCTION S04_ ATAN2_V (A , B) 
REAL A() , B() 


3 Description 


A logical mask is set up, where each element is defined by the relative magnitudes of the 
arguments to S04_ATAN2_V. Where the absolute value of an element of vector A is greater 
than that of B, the logical mask element is set to .TRUE.; for all other cases the logical mask 
element is set to .FALSE. 


$04_ATAN2.V takes the value: 





ABS(B) . 
ATAN (ee) where ABS(A) > ABS(B) (the logical mask is .TRUE.) 
i) n/2—-ATAN ( Tn) where ABS(A) < ABS(B) (the logical mask is FALSE.) 


Thus the built-in ATAN function is always presented with arguments whose values are in 
the range zero to one, and divide-by-zero errors are avoided, except when the corresponding 
elements in each argument are zero. After the ATAN operation the results are corrected 
to put their values into the correct quadrants, from —7 to 7, according to the signs of the 
arguments. 


4 References 


None 


5 Arguments 
A — REAL MATRIX 


On entry, A contains values proportional to the sines of the angles to be returned by the 
function, and is unchanged on exit. 


B —- REAL MATRIX 
On entry, B contains values proportional to the cosines of the angles to be returned by 


the function, and is unchanged on exit. 


6 Error Indicators 


None 
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Auxiliary Routines 


None 


Accuracy 


Over most of the range the results are accurate to within one part in 10°. Under worst case 
conditions, where the resultant angle is 7/4, 37/4, and so on, the error may approach two 
parts in 10°. 


Further Comments 


A program interrupt will occur if corresponding elements of A and B are both zero. 


Keywords 


Arc-tangent, inverse tangent 


Example 


In the following example the host routine sets up array ANGLES to contain the radian 
equivalents of 0, 6, 12, 18 ... degrees. The DAP routine calculates the sines and cosines of 
these angles, and then calls S04. ATAN2-V to return the original angles. 


Host program 


PROGRAM VECTESTHOST 
REAL ANGLES(32) 


COMMON/DAP/ANGLES 
Cc 
C Conversion factor from degrees to radians 
c 
F=3.14159265/180.0 
Cc 
C Initialise data for testing function 
c 
DO 1 J=1,32 
1 ANGLES (J)=FLOAT(J-1)*F*6.0 
Cc 
C Connect to DAP module 
Cc 
CALL DAPCON(’vectest.dd’) 
c 
C Send testdata to the DAP 
Cc 
CALL DAPSEN(’DAP’ , ANGLES, 32) 
Cc 
C Call the DAP ENTRY subroutine 
c 
CALL DAPENT(’ VECTESTDAP’ ) 
Cc. 
C Retrieve the results from the DAP 
c 


CALL DAPREC(’DAP’ , ANGLES , 32) 
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Cc 
C Release the DAP 
c 
CALL DAPREL 
c 
C Write out a sample selection of the data and results for inspection 
c 


WRITE(6,2)(J,ANGLES(J) , J=1,32) 
2 FORMAT(5(? ’°,12,’ ’,F9.6)) 

STOP 

END 


DAP program 


ENTRY SUBROUTINE VECTESTDAP 
REAL*4 SINVALS() ,COSVALS() , ANGLES () 
COMMON/DAP/ ANGLES 


aa 


Note the EXTERNAL statement for this function 


EXTERNAL REAL*4 VECTOR FUNCTION SO4_ATAN2_V 


RA .2Qa 


Convert input data 


@ ; CALL CONVFVE(ANGLES , 32,1) 


Q 


Calculate sine and cosine components 


SINVALS=SIN (ANGLES) 

COSVALS=COS (ANGLES) 

ANGLES=S04_ATAN2_V(SINVALS , COSVALS) 
C 


a 


Convert input results back to host format 


CALL CONVVFE(ANGLES , 32,1) 
RETURN 
END 


Results 


i -000000 2 104720 3 -209440 4 -314159 385 -418879 
6 -523599 7 -628318 8 .733039 9 837757 10 - 942478 
11 -047197 12 151917 13 1.256637 14 -361357 15 1.466076 
16 -570796 17 -675517 18 1.780236 19 -884956 20 1.989675 
2i -094396 22 -199116 23 2.303835 24 -408554 25 2.513275 
26 -617993 27 2.722714 28 2.827433 29 -932153 30 3.036873 
31 141592 32 -3.036874 


WNN & 
Nr eR 
NUN ee 
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1 Purpose 


S04.COS_INT returns the value of the cosine integral C; (x) for a matrix argument. 


2 Specification 


REAL MATRIX FUNCTION S04.COS_INT (X , EMASK) 
REAL X (,) 
LOGICAL EMASK (,) 


3 Description 


C; (x) is approximated using one of three Tschebyshev expansions. Since C; (x) is imaginary 
for z < 0, only positive arguments are considered. The expansions (and the ranges over 
which they are valid) are of the form: 


i 


2 
C;(xz) ~ In (2)+>_ a,D,(t) for «€ [0,9] and where ¢ = 2 (=) —1 


‘ 


C,(z) ~ In(z)+)_ 6,7; (t) for 2 €(9,16] and where t =2 (4 





C;(z) x f (z)sin(x)—g(x)cos(x) for zx € (16,00) 


where: 


f(z)= » cr T,(t) 


g(t) = 0 4-Tr(t) 


t=2(2)-1 
| xr 


where oy is a series equal, term for term, to 3 except that the first term in S> is half 
the first term in ye 





In the third approximation f and g are asymptotic expansions of the form: 


ra~(9(-8)*()-@) ~] 
~()6-@)@-@) -} 


As z — 00, C;(x) — 0; this fact is used by the routine for very large arguments. 
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References 
[1] ABRAMOWITZ M and STEGUNI A 


Handbook of Mathematical Functions; chapter 4 section 4, p 79: Dover Publications, 
1968. 


[2] FOX L and PARKER I 
Chebyshev Polynomials in Numerical Analysis: Oxford University Press, 1968. 


Arguments 
X —~ REAL MATRIX 


On entry, X contains the points at which the evaluation of C; is required. All elements 
of X must be defined on entry, and are unchanged on exit. 


EMASK - LOGICAL MATRIX 


On exit, EMASK indicates the positions for which the argument was non-positive (see 
Error Indicator below). 


Error Indicators 


C; (x) is undefined if z is zero, and is imaginary for negative x. In either case the result 
returned by S04.COS_INT is zero and the corresponding bit in EMASK is set . TRUE. 


Auxiliary Routines 
None 


Accuracy 


In general 6 significant figures of accuracy may be expected in the result. However, close to 
the zeros of C; (x) all relative accuracy may be lost. For very large arguments, the result is 
set to zero as the true value of C; (zx) is less than the possible inaccuracy inherent in 32 bit 
precision. 


Further Comments 


None 


Keywords 


Cosine integral function, special function 


Example 
The example calculates C; (x) for 1024 values of z between about 0.005 and 20. 


Host program 


PROGRAM MAIN 

REAL X(1024) ,¥(1024) 

COMMON /XY/X,Y 
Cc 
C Initialise data for testing function 
Cc 
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DO 1 I = 1,1024 
i X(I) = FLOAT (I) * 20.0 / 1024.0 
c 
C Connect to DAP module 
Cc 
CALL DAPCON(’ ent.dd’) 
Cc 
C Send testdata to the DAP 
Cc 
CALL DAPSEN(’XY’ ,X,1024) 
Cc 
C Call the DAP ENTRY subroutine 
c 
CALL DAPENT(’ENT?’ ) 
Cc 
C Retrieve the results from the DAP 
c 
CALL DAPREC(’XY? ,X, 2048) 
Cc 
C Release the DAP 
C 
: CALL DAPREL 
Cc 


C Write out a sample selection of the data and results for inspection 


WRITE (6,2) 
2 FORMAT (6X, ’X?, 14X, ’Ci(X) ’/) 
DO 3 I = 1,1024, 32 


3 WRITE (6,4) X(I),Y(I) 
4 FORMAT (1X,2G15.7) 
STOP 
END 


DAP program 


ENTRY SUBROUTINE ENT 
REAL X(,), Y(,) 
LOGICAL EMASK (,) 
COMMON /XY/X,Y 


c 
C Note the EXTERNAL statement for this function 
c 
EXTERNAL REAL MATRIX FUNCTION S04_COS_INT 
Cc 
C Convert input data 
c 
CALL CONVFME(X) 
Y = S04_COS_INT(X, EMASK) 
c 
C Trace out any components that may be <=0 
c 
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IF (ANY(EMASK)) TRACE 1 (EMASK) 





c 
C Convert input data and results back to host format 
c 
CALL CONVMFE(X) 
CALL CONVMFE(Y) 
RETURN 
END 
Results 
x Ci(X) 


-1953125e-01 -3.358611 


.6445313 .3590578e-01 
1.269531 .4390500 
1.894531 4428694 
2.519531 . 2795894 
3.144531 .7273293e-01 
3.769531 -.9733582e-01 
4.394531 -.1872826 
5.019531 -.1888952 
5.644531 -.1224203 
6.269531 ~.2474308e-01 
@ 6.894531 .6474495e-01 
7.519531 1165104 
8.144531 1185551 
8.769531 .7754135¢e-01 
9.394531 .1383400e-01 
10.01953 -.4708195e-01 
10.64453 ~.8390427e-01 
11.26953 ~ .8623505e-01 
11.89453 -.5696487e-01 
12.51953 -.9857178e-02 
13.14453 .3642845e-01 
13.76953 .6525517e-01 
14.39453 .6775570e-01 
15.01953 .4528236e-01 
15.64453 .7996559e-02 
16.26953 -.2936367e-01 
16.89453 -.5321791e-01 
17.51953 ~.5584693e-01 
18.14453 ~.3777995e-01 
18.76953 ~.7019278e-02 
19.39453 .2435225e-01 
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1 Purpose 


S04. MOD_BES_IO returns the value of the modified Bessel function I0 for a matrix argu- 
ment. 


2 Specification 


REAL MATRIX FUNCTION S04.MOD-BES-I0(X , EMASK) 
REAL X(,) 
LOGICAL EMASK (,) 


3 Description 


I0 is approximated using one of three Tschebyshev polynomial expansions. Since the function 
is even it is only necessary to consider positive arguments. The expansions (and the ranges 
over which they are valid) are of the form: 


10 (x) ~ exp (2) >- aiT; (t) for 2x € [0,4] and where t = 2/2—1 
10 (x) ~ exp (x) > oT; (t) for x €(4,12] and where t = 2/4—2 


I0(z)~ ee) Dan (t) for 2 €(12,c0) and where t = 24/r—1 


, d 


where > is a series equal, term for term, to SS. except that the first term in is half 
the first term in s 


4 References 
[1] ABRAMOWITZ M and STEGUNIA 
Handbook of Mathematical Functions; chapter 9 , p 374: Dover Publications, 1968. 
FOX L and PARKER I 
[2] Chebyshev Polynomials in Numerical Analysis: Oxford University Press, 1968. 


5 Arguments 
X — REAL MATRIX 


On entry, X contains the points at which the evaluation of I0 is required. All elements 
of X must be defined on entry, and are unchanged on exit. 


EMASK - LOGICAL MATRIX 


On exit, EMASK indicates the positions for which the argument was too large (see Error 
Indicator below). 
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Error Indicators 


12.6 S04. MOD_BES_IO0 


Since I0 (x) increases rapidly with zx, the result could easily overflow even for modest values 
of z. To prevent this overflow, large values are detected and the corresponding bit in EMASK 
is set . TRUE. The value returned by the function for such large arguments is that returned 


by the largest valid argument (that is, an argument of about 174). 


Auxiliary Routines 


None 


Accuracy 


The accuracy depends on the size of the argument. For small arguments (say | z| < 12) the 
error is less than about 20 parts in 10’, but the error will increase rapidly as |x| increases. ; 


Further Comments 


None 


Keywords 


Modified Bessel function, special function 


Example 


The example calculates I0 (x) for 1024 values of z between 0 and 20. 


Host program 


PROGRAM MAIN 
REAL X(1024) , ¥(1024) 
COMMON /XY/X,Y 

Cc 


.C Initialise data for testing function 


Cc 
DO 1 I=1,1024 
1 X(I) = FLOAT(I-1)*20.0/1023.0 


: Connect to DAP module 

° CALL DAPCON(’ent.dd’) 

; Send testdata to the DAP 

° CALL DAPSEN(’ XY’ ,X, 1024) 

: Call the DAP ENTRY subroutine 

° CALL DAPENT(’ENT? ) 

Cc 

C Retrieve the results from the DAP 
: CALL DAPREC(’XY’ ,X, 2048) 

Cc 
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C Release the DAP 


c 
CALL DAPREL 
c 
WRITE (6,2) 
2 FORMAT(6X, ’X’? 14X, ’I0(X)’/) 
Cc 
C Write out a sample selection of the data and results for inspection 
Cc 


DO3I1=1, 1024 , 32 


3 WRITE(6,4) X(I),Y(T) 
4 FORMAT(1X, 2G15.7) 
STOP 
END 


DAP program 


ENTRY SUBROUTINE ENT 
REAL X(,),Y(,) 
LOGICAL EMASK(,) 
COMMON /XY/X,Y 


c 
C Note the EXTERNAL statement for this function 
Cc 
EXTERNAL REAL MATRIX FUNCTION SO4_MOD_BES_IO 
C 
C Convert input data 
Cc 
CALL CONVFME(X) 
Y = SO4_MOD_BES_IO(X, EMASK) 
c 
C Trace out a mask to show where arguments were too large 
c 
IF (ANY (EMASK))TRACE 1 (EMASK) 
Cc 
C Convert input data and results back to host format 
c 


CALL CONVMFE(X) 
CALL CONVMFE(Y) 
RETURN 

END 


168 man010.02 AMT 











S - Special functions 12.6 S04. MOD. BES_I0 


Results 





x T0(X) 


.0000000e+00 1.0000000 


.6256109 1.100267 
1.251222 1.431394 
1.876832 2.094550 
2.502443 3.295993 
3.128055 5.417401 
3.753665 9.147502 
4.379276 15.72208 
5.004888 27.35907 
5.630498 4804684 
6.256109 84.97379 
6.881721 151.1240 
7.507331 269.9973 
8.132942 484.2058 
8.758554 871.1418 
9.384164 1571.584 
10.00978 2841.946 
10.63539 5149.855 
11.26100 9349 .078 
11.88661 16999.96 
12.51222 30957 .04 

© 13. 13783 56446.73 

13.76344 103046.5 
14.38905 188319. 1 
15.01466 344494.9 
15.64027 630757 .9 
16. 26588 1155853. 
16.89149 2119699. 
17.51714 3890039. 
18.14272 7143643. 
18.76833 .1312658e+08 
19. 39394 .2413416e+08 
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1 Purpose 


$04. MOD_BES_I1 returns the value of the modified Bessel function I1 for a matrix argu- 
ment. 


2 Specification 


REAL MATRIX FUNCTION S04. MOD_BES_I1(X , EMASK) 
REAL X(,) 
LOGICAL EMASK (,) 


3 Description 


I1 is approximated using 3 Tschebyshev polynomial expansions. Since I 1 (~—x) = -I1(z) it 
is only necessary to consider positive arguments. The expansions (and the ranges over which 
they are valid) are of the form: 


I1(z)~ 2° a;T; (t) for x € [0,4] and where ¢t = 2/2-1 
I1(z) ~ exp (x) 5-7; (t) for 2 €(4,12] and where t = x/4—2 


I1(z)~ eo) Dan (t) for 2 €(12,00) and where t = 24/x-1 





‘ , 
where > is a series equal, term for term, to oe except that the first term in Sy is half 
the first term in i» 


4 References 
[1] ABRAMOWITZ M and STEGUNI A 
Handbook of Mathematical Functions; chapter 9, p 374: Dover Publications 
[2] FOX L and PARKER I 
Chebyshev Polynomials in Numerical Analysis: Oxford University Press, 1968 


5 Arguments 
X ~ REAL MATRIX 


On entry X contains the points at which the evaluation of I1 is required. All elements 
of X must be defined on entry. X is unchanged on exit. 


EMASK - LOGICAL MATRIX 


On exit EMASK indicates the positions for which the argument was too large (see Error 
Indicators below). 
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6 Error Indicators 





Since I1 (x) increases rapidly with z, the result could easily overflow even for modest values 
of x. To prevent this, large values are detected and the corresponding bit in EMASK is set 
.TRUE. The value returned by the function for such large arguments is that returned by the 
largest valid argument (that is, an argument of about 174). 


7 Auxiliary Routines 


None 


8 Accuracy 


The accuracy depends on the size of the argument. For small arguments (say | z| < 12) the 
error is less than about 20 parts in 10’, but the error will increase rapidly as | z| increases. 


9 Further Comments 


None 


10 Keywords 


Modified Bessel function, special function 


11 Example 


The example calculates 11 (zx) for 1024 values of x between 0 and 20. 


© Host program 


PROGRAM MAIN 
REAL X(1024) ,¥(1024) 
COMMON /XY/X,Y 
Cc 
C Initialise data for testing function 
Cc 
DO 1 I = 1,1024 
1 X(I) = FLOAT(I1)*20.0/1023.0 


Cc 
C Connect to DAP module 
Cc 
CALL DAPCON(’? ent.dd’) 
c 
C Send testdata to the DAP 
CALL DAPSEN(’ XY’ ,X, 1024) 
c 
C Call the DAP ENTRY subroutine 
Cc 
CALL DAPENT(’? ENT?) 
Cc 
C Retrieve the results from the DAP 


CALL DAPREC(’XY’ ,X,2048) 
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Cc 
C Release the DAP 
Cc 

CALL DAPREL 
Cc 


WRITE (6,2) 
2 FORMAT (6X, ’X?,14X, *I1(X)’/) 
c 
C Write out a sample selection of the data and results for inspection. 
c 
DO 3 I = 1,1024,32 
3 WRITE (6,4) X (I) , Y(I) 
4 FORMAT (1X,2G15.7) 
STOP 
END 


DAP program 


ENTRY SUBROUTINE ENT 
REAL X(,),Y(,) 
LOGICAL EMASK(, ) 
COMMON /XY/X,Y 


: Note the EXTERNAL statement for this function 
° EXTERNAL REAL MATRIX FUNCTION SO4_MOD_BES_I1 
: Convert input data 
‘ CALL CONVFME(X) 
Y=S04_MOD_BES_I1(X, EMASK) 
: Trace out a mask to show where arguments were too large 
° IF (ANY(EMASK))TRACE 1 (EMASK) 
: Convert input data and results back to host format 
c 


CALL CONVMFE(X) 
CALL CONVMFE(Y) 
RETURN 

END 
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Results 





x I1(X) 


-0000000e+00 -0000000e+00 


6256109 . 3283606 
1.251222 - 7562914 
1.876832 1.416910 
2.502443 2.522305 
3.128055 4.436992 
3.753665 7.805889 
4.379276 13.78311 
5.004888 24.44524 
5.630498 43 .54034 
6.256109 77.84995 
6.881721 139.6668 
7.507331 251.3122 
8.132942 453.3796 
8.758554 819.7910 
9.384164 1485 .328 
10.00978 2696 .016 
10.63539 4901.422 
11.26100 8923.789 
11.88661 16268 .36 
_ 12.51222 29692 .97 
© 13.13783 54254.05 
13. 76344 99229.38 
14.38905 181652.6 
15.01466 332817 .7 
15 .64027 610248 .1 
16. 26588 1119740. 
16.89149 2055966. 
17.51711 3777319. 
18.14272 6943891. 
18.76833 .1277195e+08 
19.39394 - 2350347 e+08 
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1 Purpose 


: * sin(u) : 
$04 SIN_INT returns Si(x) = — at for a matrix argument. 
0 


2 Specification 


REAL MATRIX FUNCTION S04 _SIN_INT (X) 
REAL X(,) 


3 Description 


S; (2) is approximated using one of three Tschebyshev polynomial expansions. 
5S; (—z) = S; (x), so it is only necessary to consider positive arguments. The expansions (and 
the ranges over which they are valid) are of the form: 


d 2 
S;(z) x2) -a,T; (2) for zx € [0,9] and where t=2(=) —1 





5: (2) ~ 2) > 6, T,(t) for zx €(9,16] and where ¢ = 2 (Z A *) 1 
S; (x) ~ 1/2—f (x) cos(z)—g(x)sin(z) for z € (16,00) 
where: 


f(z)= doo Tt (t) 


g(z)= od, T, (t) 


t=2(2)-1 
zt 


‘ i 
> is a series equal, term for term, to ss except that the first term in s is half 
the first term in Ss 


In the third approximation f and g are asymptotic expansions of the form: 


ro~()-@)+(8)-@) =} 
v~()b-@)+)-@) »} 


As x — +00, S; (x) — +7/2; this fact is used by the routine for very large arguments. 
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10 


11 


References 
[1] ABRAMOWITZ M and STEGUNIA 


Handbook of Mathematical Functions; chapter 5 section 2, p 231: Dover Publications, 
1968. 


[2] FOX L and PARKER I 
Chebyshev Polynomials in Numerical Analysis: Oxford University Press; 1968. 


Arguments 
X —- REAL MATRIX 


On entry, X contains the points at which the evaluation of S; is required. All elements 
of X must be defined on entry, and are unchanged on exit. 


Error Indicators 


None 


Auxiliary Routines 


None 


Accuracy 


The maximum error should be less than about 20 parts in 10’. 


Further Comments 
None 


Keywords 


Sine integral function, special function 


Example 


The example calculates S; for 1024 values of x between —10 and 10. 


Host program 


PROGRAM MAIN 
REAL X(1024) , ¥(1024) 
COMMON /XY/X,Y 
c 
C Initialise data for testing function 
Cc 
DO 1i1TI=1, 1024 
1 X(I) = FLOAT (I-1)*20.0 / 1023.0 - 10.0 
Cc 
C Connect to DAP module 
c 
CALL DAPCON(’ ent.dd’) 
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Cc 
C Send testdata to the DAP 
Cc 
CALL DAPSEN(’ XY’ ,X, 1024) 
c 
C Call the DAP ENTRY subroutine 
Cc 
CALL DAPENT(’ENT? ) 
Cc 
C Retrieve the results from the DAP 
c 
CALL DAPREC(’ XY’ ,X, 2048) 
c 
C Release the DAP 
c 
CALL DAPREL 
c 
WRITE (6,2) 
2 FORMAT(6X, ’X’, 14X, ’Si(X)’/) 
Cc 


C Write out a sample selection of the data and results for inspection 
Cc 
DO 3 I = 1,1024,32 
3 WRITE (6,4) X(I), Y(I) 
4 FORMAT(1X, 2615.7) 
STOP 
END 


DAP program 


ENTRY SUBROUTINE ENT 
REAL X(,) , Y(,) 
COMMON /XY/X,Y 


c 
C Note the EXTERNAL statement for this function 
C 

EXTERNAL REAL MATRIX FUNCTION SO4_SIN_INT 
c 
C Convert input data 
c 

CALL CONVFME(X) 

Y= SO4_SIN_INT (X) 
c 
C Convert input data and results back to host format 
C 


CALL CONVMFE(X) 
CALL CONVMFE(Y) 
RETURN 

END 
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Results 
x Si(X) 
-10.000000 -1.658348 
~9.374389 -1.674626 
-8.748778 -1.650258 
~8.123167 -1.589128 
-7.497556 -1.510376 
-6.871944 -1.443393 
-6. 246334 -1.418261 
-5.620723 -1.454368 
-4.995112 1.550871 
-4.369501 -1.682421 
-3.743890 -1.802158 
~3.118279 -1.851851 
~2.492668 -1.776752 
-1.867058 1.541133 
-1.241446 -1.139938 
-.6158361 -.6030076 
.9775162e-02 .9775121e-02 
.6353865 .6213064 
1.260997 1.154774 
1.886608 1.551066 
2.512219 1.781414 
© 3.137830 1.851934 
3.763441 1.799163 
4.389051 1.678203 
5.014663 1.547130 
5.640274 1.452258 
6.265884 1.418175 
6.891495 1.444993 
7.517107 1.512826 
8.142717 1.591439 
8.768328 1.651638 
9.393940 1.674711 
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Purpose 


S15_ERF returns the value of the error function. 


Specification 


REAL*8 MATRIX FUNCTION S15_ERF (X) 
REAL*8 X(,) 


Description 


The function is calculated by one of three algorithms. The algorithms used (and the ranges 
over which they are valid) are: 


9 


jerf(x)|=|2z|Ti(T) for |2z|€ [0,2] and where T= =-1 


exp(—z”) _ 2-7 
fale T2(T) for |2|€(2,XHIGH) and where T = —— 


|erf(x)| = 1- Pai 


Jerf(x)|=1 for |2| € [XHIGH, co} 


where XHIGH is the value above which erf(z) = 1, to the machine’s accuracy; XHIGH 
is machine-dependent, and is 6.25 for the DAP 


The sign of erfx) is the same as that of 2; T\(T) and T2(T) are Tschebychev polynomial 
expansions. They are evaluated using recursive descent by the function ‘ZTSCHEB’, which 
has as parameters the dimension and array of coefficients for the expansion. The argument 
‘T’ is passed in the named common block ’CTSCHEBARG’. 


References 
{1] ABRAMOWITZ M and STEGUNI A 


Handbook of Mathematical Functions; chapter 7 section 1, p 297: Dover Publications, 
1968. 


Arguments 
X —- REAL*8 MATRIX 


On entry, X contains the points at which the function is to be evaluated. All elements 
of X must be assigned on entry; X is unchanged on exit. 


Error Indicators 


None 


Auxiliary Routines 
The routine calls the General Support library routine ZTSCHEB. 


man010.02 AMT 











S ~ Special functions 12.9 S15. ERF 


8 Accuracy 


The DAP works to a precision of about 17 significant figures in REAL*8 arithmetic. $15_ERF 
was checked against $15. ERFC according to the relation: 


erf(z) + erfce(z) = 1 





The worst error was 7 E-16, and the median error was about 2 E-16. 


9 Further Comments 


The routine uses the common block ‘CTSCHEBARG’ to pass a parameter to the function 
‘ZTSCHEB’, so you must not use a block of that name. 


10 Keywords 


Error function, special function 


11 Example 


The following example program reads and prints a caption and then reads pairs of numbers 
from the data stream. The program assumes that the first number of each pair indicates 
whether the second number in the pair is a valid argument of the function. Reading of the 
pairs of numbers continues until the first number in a pair is negative. 


The program packs the arguments into the first column of a 32 by 32 array, X, which is 

passed by the named common block COM1 to the DAP entry subroutine DAPSUB. The 

subroutine converts the values into DAP storage mode, then calls S15_ERF. The result is 

assigned to matrix Y, which is also in common block COM1. Both matrices are converted 
© back into host storage mode and the results printed. 


Host program 


PROGRAM MAIN 


INTEGER INUM(32,32) 
CHARACTER*40 TITLE 

COMMON /COM1/X(32,32),Y(32,32) 
DOUBLE PRECISION X,Y 


c 
C Initialise X to avoid ’UNASSIGNED VARIABLE’ 
Cc 

DO 2 J = 1,32 

DO iI = 1,32 

X(I,J) = 0.0 


1 CONTINUE 
2 CONTINUE 


READ (*,5) TITLE 
WRITE (*,6) TITLE 
WRITE (*,7) 
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Cc 
C Read data 
Cc 
J=0 
3° J=IJ+1 
READ (*,8) INUM(J,1), X(J,1) 
IF (INUM(J,1).GE.0)GOTO3 
Cc 
C Connect to DAP module 
Cc 
CALL DAPCON(’dapsub.dd’) 
Cc 
C Send test data to DAP 
c 
CALL DAPSEN(’?COM1’ ,X, 2048) 
Cc 
C Call DAP routine 
Cc 
CALL DAPENT(’DAPSUB’? ) 
Cc 
C Receive test data and results from DAP 
Cc . 
CALL DAPREC(’COM1’ ,X,4096) 
Cc . 
C Release the DAP 
Cc 
CALL DAPREL 
Cc 
C Write out results 
Cc 
J=z=JjJ-1 
DO 4 I=1,J 
4 WRITE (*,9) X(I,1), Y(I,1), INUM(I,1) 
STOP 
5 FORMAT (A) 
6 FORMAT (4(1X/), 1H , A, 8H RESULTS/1X) 
7 FORMAT (18X, ’X’, 25X, ’Y’, 13X, ’INUM’) 
8 FORMAT (I5, F20.5) 
9 FORMAT (4X, 1PD20.3, 1X, 1PD20.3, 14X, I2) 


END 


DAP program 


ENTRY SUBROUTINE DAPSUB 
C ; 

C Note the use of the external statement for this function 
Cc 

EXTERNAL REAL*8 MATRIX FUNCTION Si5_ERF 

COMMON /COM1/ X(,),Y(,) 

REAL*8 X,Y 
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c 


C Convert input data 


Cc 


CALL CONVFMD(X) 


c 


Y(,) = S15_ERF(X) 


Cc 


C Convert input data and results back to host mode 


Cc 


CALL CONVMFD(X) 
CALL CONVMFD(Y) 


RETURN 
END 


Data 


SiSERF EXAMPLE PROGRAM DATA 


BOO PWN 


Results 


SiSERF EXAMPLE PROGRAM DATA 


-6.0 


oomoouw 


x 
-6.000e+00 
-4.500e+00 
-1.000e+00 

1.000e+00 
4.500e+00 
6.000e+00 


General Support library 


RESULTS. 


Y 
-1.000e+00 
~1.000e+00 
-8.427e-01 

8.427e-01 
1.000e+00 
1.000e+00 
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1 Purpose 


S15. ERFC returns the value of the complement of the error function. 


2 Specification 
REAL*8 MATRIX FUNCTION S15_ERFC (X) 
REAL*8 X(,) 


3 Description 


S15. ERFC returns the complement of the error fucntion $15. ERC. $15_ ERFC is calculated 
by one of four algorithms. The algorithms used (and the ranges over which they are valid) 
are: 


erfc(z) = 2.0 (to machine accuracy) for zr €(—co, XLOW) 
erfc(z) = 2.0—exp(—z”) POLY(T) for z € [XLOW,0) 
erfe(z) = exp(—z”) POLY(T) for z € {0,XHIGH) 

erfc(z) = 0.0 (to machine accuracy) for zx € [XHIGH, oo) 


where: 


XLOW and XHIGH are values that are machine-dependent; for the DAP they are 
~6.25 and 13.0 respectively 


POLY{( T ) is a Tschebychev polynomial function of T, where: 


_ |z| — 3.75 
~ |x| + 3.75 


and is calculated by conversion to an ordinary polynomial, which is then evaluated 
by Horner’s method. 
4 References 
[1] ABRAMOWITZ M and STEGUNIA 


Handbook of Mathematical Functions; chapter 7 section 1, p 297: Dover Publications, 
1968. 


5 Arguments 
X - REAL*8 MATRIX 


On entry, X contains the points at which the function is to be evaluated. All elements 
of X must be assigned on entry; X is unchanged on exit. 


6 Error Indicators 


None 
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10 


ll 


Auxiliary Routines 


None 


Accuracy 


If E and D are the relative errors in result and argument respectively, they are in principle 
related by: 


2x exp(—z?) 


ae Jr erfc(z) 








22 


Vr 


You should note that near x = 0 the amplification factor behaves as , hence the accuracy 


is also largely determined by machine precision. 
exp(—2?) 


Va 


For large positive x ,the factor behaves like 2x” and hence to a certain extent relative accuracy 
is unavoidably lost. However the absolute error in the result, E, is given by: 


For large negative x, where the factor is z , accuracy is mainly limited by machine 


precision. 


2x exp(—z) 


Va 


so absolute accuracy can be guaranteed for all z. 


|E| = D 








Further Comments 
None 


Keywords 


Complementary error function, special function. 


Example 


The following example program reads and prints a caption and then reads pairs of numbers 
from the data stream. The program assumes that the first number of each pair indicates 
whether the second number in the pair is a valid argument of the function. Reading of the 
pairs of numbers continues until the first number in a pair is negative. 


The program packs the arguments into the first column of a 32 by 32 array, X, which is 
passed by the named common block COM1 to the DAP entry subroutine DAPSUB. The 
subroutine converts the values into DAP storage mode, then calls $15_ERFC. The result is 
assigned to matrix Y, which is also in common block COM1. Both matrices are converted 
back into host storage mode and the results printed. 


Host program 


PROGRAM MAIN 

Cc 

C S15_ERFC example program 

Cc 
INTEGER IFAIL(32,32) 
CHARACTER*40 TITLE 
COMMON /COM1/X(32,32) ,Y(32,32) 
DOUBLE PRECISION X,Y 
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Cc 
C Initialise X to avoid 
C *?UNASSIGNED VARIABLE’ 


Cc 

DO 2 J = 1,32 

DO 1 I = 1,32 

X(I,J) = 0.0 

1 CONTINUE 

2 CONTINUE 
Cc 

READ (+*,5) TITLE 

WRITE (*,6) TITLE 

WRITE (*,7) 
c 
C Read data 
Cc 

J=0 
3 J=J+1 

READ (*,8) IFAIL(J,1), X(J,1) 

IF (IFAIL(J,1).GE.0)GOTO3 
Cc 
C Connect to DAP module 
c 

CALL DAPCON(’dapsub.dd’) 
c 
C Send test data to DAP 
c 

CALL DAPSEN(’COM1? ,X, 2048) 
Cc 
C Call DAP routine 
Cc 

CALL DAPENT(’DAPSUB’ ) 
Cc 
C Receive test data and results from DAP 
Cc 

CALL DAPREC(’COM1’ ,X,4096) 
Cc 
C Release the DAP 
c 

CALL DAPREL 
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Cc 
C Write out results 
Cc 
J=zjJ-i 
DO 4 I=1,J 
4. WRITE (*,9) X(I,1), Y(I,1), IFAIL(I,1) 
5 FORMAT (A) 
6 FORMAT (4(1X/), 1H , A, 8H RESULTS/1iX) 
7 FORMAT (18X, °X’, 25X, °Y’,13X, ’INUM’) 
8 FORMAT (I5, F20.5) 
9 FORMAT (4X, 1PD20.3, 1X, 1PD20.3, 14X, I2) 
STOP 
END 


DAP program 


ENTRY SUBROUTINE DAPSUB 


Cc 
C Note the use of the external statement for this function 
Cc 
EXTERNAL REAL*8 MATRIX FUNCTION Si5_ERFC 
COMMON /COM1/ X(,),Y(,) 
REAL#8 X,Y : 
c 
C Convert input data 
Cc 
CALL CONVFMD(X) 
Cc 
Y(,) = S15_ERFC(X) 
C 
C Convert input data and results back to host mode 
Cc 
CALL CONVMFD(X) 
CALL CONVMFD(Y) 
RETURN 
END 
Data 


SiS5ERFC EXAMPLE PROGRAM DATA 


1 ~10.0 
2 ~1.0 
3 -0 
4 1.0 
5 15.0 
-1 0.0 
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Results 
SIS5ERFC EXAMPLE PROGRAM DATA RESULTS 

‘ xX Y INUM 

-1.000e+01 2.000e+00 es ; 1 

-1.000e+00 1.843e+00 2 
0.000e+00 : 1.000e+00 3 
1.000e+00 1.573e-01 4 
1.500e+01 0.000e+00 5 
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X01 — Mathematical constants 


Contents: 


Subroutine 


X01. PI 
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Purpose 
X01_ PI provides the value of pi for any of the real precision lengths available on the DAP. 


Specification 


SUBROUTINE X01. PI(PI , LEN) 
REAL* <LEN> PI 
INTEGER LEN 


Description 


The relevant value is picked out from a table of values. 


References 


None 


Arguments 
PI - REAL* <LEN> 
On exit, PI contains the value of w for reals of length LEN bytes. 


LEN — INTEGER 


On entry, LEN must contain the length in bytes of PI (in the range 3 to 8). If LEN is 
outside the range 3 to 8 the results are unpredictable. LEN is unchanged on exit. 


Error Indicators 
None 


Auxiliary Routines 
This routine references the General Support library routine Z_X01_X02. AUX. 


Accuracy 


The results are to machine accuracy for the precision required. 


Further Comments 


None 


Keywords 


Machine constants, pi 


Example 
The following FORTRAN-PLUS fragment traces out the REAL*4 value for 7. 
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ENTRY SUBROUTINE ENT 
REAL*4 PI 

CALL X01_PI(PI, 4) 
TRACE 1 (PI) 

RETURN 

END 





Results 


FORTRAN-PLUS Trace 
FORTRAN-PLUS Subroutine: ENT at Line 4 


Real Scalar Local Variable PI in 32 bits - on Stack at 0.09 
3.1415930E+00 


End of Report 
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Chapter 14 


X02 — Machine constants 


Contents: 


Subroutine 
X02. EPSILON 
X02. MAXDEC 
X02. MAXINT 
X02.MAXPW2 
X02. MINPW2 
X02. RMAX 
X02_RMIN 


X02_TOL 
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Purpose. 


X02. EPSILON provides the smallest positive real (EPS) such that 1.0 + EPS differs from 
1.0, for any of the real precision lengths available on the DAP. 


Specification 
SUBROUTINE X02_ EPSILON (EPSILON, LEN) 
REAL* <LEN> EPSILON 
INTEGER LEN 

Description 


The relevant value is picked out from a table of values. 


References 


None 


Arguments 


EPSILON - REAL* <LEN> 
On exit, EPSILON contains the value of EPS for reals of length LEN bytes. 


LEN - INTEGER 


On entry, LEN must contain the length in bytes of EPSILON (in the range 3 to 8). If © 
LEN is outside the range 3 to 8 the results are unpredictable. LEN is unchanged on exit. 





Error Indicators 


None 


Auxiliary Routines 
The routine references the General Support library routine Z_X01_ X02. AUX. 


Accuracy 


The results are to machine accuracy for the precision required. 


Further Comments 


None 


Keywords 


Machine constants, machine precision 


Example 
The following FORTRAN-PLUS fragment traces out the REAL*4 value of e. 
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ENTRY SUBROUTINE ENT 
REAL*4 EPS 

CALL X02_EPSILON(EPS ,4) 
TRACE 1 (EPS) 

RETURN 

END 





Results 


FORTRAN-PLUS Trace 
FORTRAN-PLUS Subroutine: ENT at Line 4 


Real Scalar Local Variable EPS in 32 bits - on Stack at 0.09 
9.5367432E-07 


End of Report 
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Purpose 


X02. MAXDEC provides a value for MAXDEC for the range of reals of different precision 
available on the DAP; MAXDEC is the maximum number of decimal digits which can be 
accurately represented over the whole range of floating point numbers. 


Specification 


SUBROUTINE X02. MAXDEC (M , LEN) 
INTEGER M , LEN 


Description 


The relevant value is picked out from a table of values. 


References 


None 


Arguments 


M - INTEGER 
On exit, M contains the value of MAXDEC for reals of length LEN bytes. 


LEN - INTEGER 


On entry LEN must contain the length in bytes of the reals for which MAXDEC is 
required (in the range 3 to 8). If LEN is outside the range 3 to 8 the results are unpre- 
dictable. Unchanged on exit. 


Error Indicators 


None 


Auxiliary Routines 


None 


Accuracy 


Whilst the results given are accurate for any particular real number, precision may be lost 
after a sequence of arithmetic operations. 


Further Comments 


None 


Keywords 


Machine constants, real precision 


Example 


The following FORTRAN-PLUS fragment traces out the maximum number of decimal digits 
which can be accurately represented over the whole range of REAL*4 precision floating point 
numbers. 
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ENTRY SUBROUTINE ENT 
INTEGER MAXD 

CALL X02_MAXDEC(MAXD ,4) 
TRACE 1 (MAXD) 

RETURN 

END 





Results 


FORTRAN-PLUS Trace 
FORTRAN-PLUS Subroutine: ENT at Line 4 


Integer Scalar Local Variable MAXD in 32 bits - on Stack at 0.09 
6 


End of Report 
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Purpose 


X02.MAXINT provides a value for MAXINT for the range of integers of different precision 
available on the DAP; MAXINT is the largest integer such that MAXINT and -MAXINT 
can both be represented exactly. 


Specification 
SUBROUTINE X02_.MAXINT(M , LEN) 
INTEGER* <LEN> M 
INTEGER LEN 

Description 


The relevant value is picked out from a table of values. 


References 


None 


Arguments 


M - INTEGER* <LEN> 
On exit, M contains the value of MAXINT for integers of length LEN bytes. 


LEN ~- INTEGER 
On entry, LEN must contain the length in bytes of M (in the range 1 to 8). If LEN is 
outside the range 1 to 8 the results are unpredictable. LEN is unchanged on exit. 


Error Indicators 
None 


Auxiliary Routines 
The routine references the General Support library routine Z_X01_X02_ AUX. 


Accuracy 


The results returned are to machine accuracy for the precision required. 


Further Comments 


None 


Keywords 


Machine constants, maximum integer 


Example 


The following FORTRAN-PLUS fragment traces out the value of MAXINT for INTEGER*4 
precision. 
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ENTRY SUBROUTINE ENT 
INTEGER MAXI 

CALL XO2_MAXINT(MAXI,4) 
TRACE 1 (MAXI) 

RETURN 

END 





Results 


FORTRAN-PLUS Trace 
FORTRAN-PLUS Subroutine: ENT at Line 4 


Integer Scalar Local Variable MAXI in 32 bits - on Stack at 0.09 
2147483647 


End of Report 
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Purpose 


X02. MAXPW2 provides a value for MAXPW2 for the range of reals of different precision 
available on the DAP; MAXPW2 is the largest integer power to which 2.0 may be raised 
without overflow. 


Specification 
SUBROUTINE X02. MAXPW2(M) 
INTEGER* <2-4> M 
Description 


The relevant value is picked out from a table of values. 


References 


None 


Arguments 


M ~ INTEGER* <2-4> 
On exit, M contains the value of MAXPW?2 for reals of any length 


Error Indicators 
None 


Auxiliary Routines 
None 


Accuracy 


The accuracy does not depend on the precision used. 


Further Comments 
None 


Keywords 


Machine constants; maximum power of 2 


Example 


The following FORTRAN-PLUS fragment traces out the largest integer power to which 2.0 
may be raised without overflow for any real precision length. 


ENTRY SUBROUTINE ENT 
INTEGER MAXPW2 

CALL X02_MAXPW2(MAXPW2) 
TRACE 1 (MAXPW2) 

RETURN 

END 


man010.02 AMT 











X02 — Machine constants 14.4 X02. MAXPW2 


Results 





FORTRAN-PLUS Trace 
FORTRAN-PLUS Subroutine: ENT at Line 4 


Integer Scalar Local Variable MAXPW2 in 32 bits - on Stack at 0.09 
251 


End of Report 
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Purpose 


X02. MINPW2 provides a value for MINPW2 for the range of reals of different precision 
available on the DAP; MINPW2 is the largest negative integer power to which 2.0 may be 
raised without underflow. , 


Specification 
SUBROUTINE X02. MINPW2(M) 
INTEGER* <2-4> M 
Description 


The relevant value is picked out from a table of values. 


References 


None 


Arguments 


M - INTEGER* <2-4> 
On exit, M contains the value of MINPW2 for reals of any length. 


Error Indicators 
None 


Auxiliary Routines 
None 


Accuracy 


The accuracy does not depend on the precision used. 


Further Comments 


None 


Keywords 


Machine constants, maximum negative power of 2 


Example 


The following FORTRAN-PLUS fragment traces out the largest negative integer power to 
which 2.0 may be raised without underflow for any real precision length. 


ENTRY SUBROUTINE ENT 
INTEGER MINPW2 

CALL X02_MINPW2(MINPW2) 
TRACE 1 (MINPW2) 

RETURN 

END 
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Results 





FORTRAN-PLUS Trace 
FORTRAN-PLUS Subroutine: ENT at Line 4 


Integer Scalar Local Variable MINPW2 in 32 bits - on Stack at 0.09 
251 


End of Report 
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Purpose 


X02_RMAX provides the largest real (RMAX) such that RMAX and -RMAX can both be 
represented exactly, for the range of reals of different precision available on the DAP. 


Specification 
SUBROUTINE X02. RMAX(R , LEN) 
REAL* <LEN> R 
INTEGER LEN 

Description 


The relevant value is picked out from a table of values. 


References 


None 


Arguments 


R - REAL* <LEN> 
On exit, R contains the value of RMAX for reals of length LEN bytes. 


LEN ~ INTEGER : 
On entry, LEN must contain the length in bytes of R (in the range 3 to 8). If LEN is 
outside the range 3 to 8 the results are unpredictable. LEN is unchanged on exit. 


Error Indicators 


None 


Auxiliary Routines 
The routine references the General Support library routine Z.X01_X02_AUX. 


Accuracy 


The results returned are as accurate as possible for the precision required. 


Further Comments 


None 


Keywords 


Machine constants, maximum real value. 


Example 


The following FORTRAN-PLUS fragment traces out the value of RMAX for REAL*4 pre- 
cision. 
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ENTRY SUBROUTINE ENT 
REAL*4 RMAX 

CALL X02_RMAX(RMAX,4) 
TRACE 1 (RMAX) 

RETURN 

END 





Results 


FORTRAN-PLUS Trace 
FORTRAN-PLUS Subroutine: ENT at Line 4 


Real Scalar Local Variable RMAX in 32 bits - on Stack at 0.09 
7.2370051E+75 


End of Report 
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Purpose 


X02_RMIN provides the smallest real (RMIN) such that RMIN and -RMIN can both be 
represented exactly, for the range of reals of different precision available on the DAP. 


Specification 
SUBROUTINE X02. RMIN (R , LEN) 
REAL* <LEN> R 
INTEGER LEN 

Description 


The relevant value is picked out from a table of values. 


References 


None 


Arguments 


R ~ REAL* <LEN> 
On exit, R contains the value of RMIN for reals of length LEN bytes. 


LEN - INTEGER 


On'entry, LEN must contain the length in bytes of R (in the range 3 to 8). If LEN is 
outside the range 3 to 8 the results are unpredictable. LEN is unchanged on exit. 


Error Indicators 


None 


Auxiliary Routines 
The routine references the General Support library routine Z_X01.X02_AUX. 


Accuracy 


The results returned are as accurate as possible for the precision required. 


Further Comments 


None 


Keywords 


Machine constants, minimum real value. 


Example 


The following FORTRAN-PLUS fragment traces out the value of RMIN for REAL*4 preci- 
sion. 
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ENTRY SUBROUTINE ENT 
REAL*4 RMIN 

CALL X02 RMIN(RMIN, 4) 
TRACE 1 (RMIN) 
RETURN 

END 





Results 


FORTRAN-PLUS Trace 
FORTRAN-PLUS Subroutine: ENT at Line 4 


Real Scalar Local Variable RMIN in 32 bits - on Stack at 0.09 
5.3976053E-79 


End of Report 
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Purpose 


X02_TOL provides the value of TOL (= RMIN/EPSILON) for the range of reals of different 
precision available on the DAP. 


Specification 
SUBROUTINE X02-TOL(R , LEN) 
REAL* <LEN> R 
INTEGER LEN 

Description 


The relevant value is picked out from a table of values. 


References 


None 


Arguments 
R - REAL* <LEN> 
On exit, R contains the value of TOL for reals of length LEN bytes. 


LEN ~ INTEGER 


On entry, LEN must contain the length'in bytes of R (in the range 3 to 8). If, LEN is 
outside the range 3 to 8 the results are unpredictable. LEN is unchanged on exit. 


Error Indicators 
None 


Auxiliary Routines 
The routine references the General Support library routine Z_X01.X02_AUX. 


Accuracy 


The results returned are as accurate as possible for the precision required. 


Further Comments 


None 


Keywords 


Machine constants 


Example 
The following FORTRAN-PLUS fragment traces out the value of TOL for REAL*4 precision. 
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ENTRY SUBROUTINE ENT 
REAL*4 TOL 

CALL X02_TOL(TOL, 4) 
TRACE 1(TOL) 

RETURN 

END 





Results 


FORTRAN-PLUS Trace 
FORTRAN-PLUS Subroutine: ENT at Line 4 


Real Scalar Local Variable TOL in 32 bits - on Stack at 0.09 
5.6597994E-73 


End of Report 
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X05 — Other utilities 


Contents: 


Subroutine 

X05. ALT_LV 
X05_CRINKLE 
X05. EAST. BOUNDARY 
X05.E.MAX PC 
X05.E.MAX_PR 
X05_E.MAX VC 
X05. E.MAX_VR 
X05. E.MIN. PC 
X05. E_MIN.PR 
X05. E.MIN_-VC 
X05_E.-MIN_VR 
X05_ EXCH _P 


X05_GATHER.V_32 
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Subroutine 

X05_I.MAX PC 

X05.I1._ MAX PR 
X05.1.MAX _VC 
X05.I1.MAX _VR 
X05.1.MIN_PC 
X05_I.MIN.PR 
X05_I.MIN_VC 
X05.1.MIN_VR 

X05. LOG2 

X05. LONG. INDEX 

X05. NORTH ~-BOUNDARY 
X05. PATTERN 
X05_SCATTER_V_32 
X05.SHLC_LV 
X05.SHLP_LV 
X05_SHORT_INDEX 
X05.SHRC_LV 
X05.SHRP_LV 
X05.SOUTH . BOUNDARY 
X05.STRETCH 4 
X05.STRETCH .8 
X05_STRETCH _N 
X05.SUM_LEFT_I2 
X05_SUM-RIGHT_I2 
X05-UNCRINKLE 
X05_WEST. BOUNDARY 
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Purpose 


X05_ALT.LV produces a long vector of alternating groups of N false values followed by N 
true values and so on until all components of the vector have a value. If the value of N lies 
outside the range 1 to 1024 all components will have the value .FALSE. 


Specification 
LOGICAL MATRIX FUNCTION X05_ALT_LV (N) 
INTEGER N 

Description 


The required pattern is set up by first producing a long vector containing the values 0 to 
1023 in long vector order. The vector is divided by N and the required pattern supplied by 
the least significant bit plane of the resulting vector. 


References 


None 


Arguments 
N - INTEGER 


On entry, N specifies the number of false and true values to be repeated alternately. N | 
is unchanged on exit. 


Error Indicators 


None 


Auxiliary Routines 
The routine calls the DAP library routine X05. LONG_INDEX. 


Accuracy 
Not applicable 


Further Comments 


None 


Keywords 


None 


Example 


This FORTRAN-PLUS fragment demonstrates the use of the function X05. ALT_LV to 
initialise alternate groups of five elements of the long vector X with different values. 
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SUBROUTINE TLVA 


REAL X(,) 
LOGICAL LM(,) 


EXTERNAL LOGICAL MATRIX FUNCTION XO5_ALT_LV 
LM=X05_ALT_LV(5) 

X=0.0 

X(LM)=1.0 


RETURN 
END 
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15.2 X05_CRINKLE release 1 





1 Purpose 


X05.CRINKLE effects a transformation in data storage format for vertical mode data occu- 
pying an array of matrices ~ from ‘sliced’ to ‘crinkled’ storage. 


2 Specification 


SUBROUTINE X05_CRINKLE (S, L,NR, NC, IFAIL) 
<any type, any length> S(,,NR,NC) 
INTEGER L, NR, NC, IFAIL 


3 Description 


The data is conceptually considered to occupy an array C of components of size 32 NR by 
32 NC. (NR or NC are positive integers, not excluding 1). The storage area, S, is an NR by 
NC array of matrices. In the ‘sliced’ format: 


S (ins fey irs Je) = C (in-+82(jp—1), fc-432 (je-1)) 


that is, each value of j, selects a contiguous group of 32 rows of C, and so on. 


In the ‘crinkled’ format: 
Ss (a te, Ir; Je) =C (jr +NRip_1, Je +NC (i-—1)) 


that is, each value of i, selects a contiguous group of NR rows of C, and so on. 


© In the ‘sliced’ format the conceptual array is divided into subarrays of size 32 by 32. In the 
‘crinkled’ format the conceptual array is divided into subarrays of size NR by NC. 


To carry out the transformation, first a mapping transformation is done on East — West 
vertical sections of the data area. Each section is regarded as an array of 32NC data items; 
each item is of length L by NR (vertical) bits. The transformation reverses the mapping 
order so that succesive horizontal sets of NC data items are rethreaded vertically. 


Then a similar transformation is done on NC separate groups of North —- South vertical 
sections of the data area. Each section of each group is regarded as an array of 32NR data 
items; each item is of length L (vertical) bits. The transformation reverses the mapping 
order so that successive horizontal sets of NR data items are rethreaded vertically. 


4 References 


None 


5 Arguments 


S — <any type, any length> MATRIX array of dimension (,,NR,NC) 


On entry, S contains the sliced data to be reformatted. On exit, S contains the data in 
crinkled form. 


L - INTEGER 


On entry, L specifies the length in bits of the components of S; L is unchanged on exit. 


NR ~ INTEGER 


On entry, NR specifies the first unconstrained dimension of S; NR is unchanged on exit. 
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Arguments - continued 
NC - INTEGER 


On entry, NC specifies the second unconstrained dimension of S; NC is unchanged on 
exit. 


IFAIL - INTEGER 


Unless the routine detects an error (see Error Indicators below) IFAIL contains zero 
on exit. 


Error Indicators 

Errors detected by the routine: 
IFAIL = 1 either NR or NC was less than 1 
IFAIL = 2 L was less than 1 


Auxiliary Routines 


None 


Accuracy 
Not applicable 


Further Comments 


None 


Keywords 


Crinkled data storage, data formatting, data movement, sliced data storage 


Example 


This FORTRAN-PLUS fragment shows how the routine can be used in an entry subroutine 
to convert a matrix set from sliced to crinkled form. 


ENTRY SUBROUTINE ENT 

REAL A(, ,2,2) 

COMMON /A/A 

DO 10 I=1,2 

DO 10 J=1,2 

CALL CONVFME(A(,,I,J)) 

10 CONTINUE 

CALL X05_CRINKLE(A,32,2,2,IFAIL) 

IF (IFAIL.NE.O) RETURN 
c DAP processing 

RETURN 

END 
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1 Purpose 


X05. EAST. BOUNDARY returns a logical matrix containing at most one . TRUE. element 
in each row, corresponding to the last .TRUE. (if any) in each row of the logical matrix 
parameter. That is, the subroutine is equivalent to the FORTRAN-PLUS code: 


KM = .FALSE. 
DO 101 = 1, 32 
IF (.NOT. ANY(LM(I,))) GOTO 10 
KM (I,) = REV(FRST (REV (LM (I, )))) 
10 CONTINUE 
2 Specification 


LOGICAL MATRIX FUNCTION X05_EAST. BOUNDARY (LM) 
LOGICAL LM(,) 


3 Description 


The DAP store plane (logical matrix LM) passed to the routine is treated as a set of 32 
logical vectors, arranged so that each vector occupies a complete row. Each of these vectors 
is dealt with independently, but in parallel. 


To each vector is ripple-added a row of all true bits; the easternmost bit of the vector is 

treated as least significant. The addition is thrown away; the row of carry bits from the 

: addition, and a shifted-west version of the row of carries, are XORed to give a vector with | 

> only one true element: the easternmost .TRUE. element in each input vector. The 32 
resultant vectors, produced in parallel, form the required east boundary matrix. 


4 References 


None 


5 Arguments 


LM ~ LOGICAL MATRIX 
On entry, LM is the logical matrix whose east boundary is required. LM is unchanged 
on exit. 


6 Error Indicators 


None 


7 Auxiliary Routines 


None 


8 Accuracy 
Not applicable 


9 Further Comments 


None 
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Boundary 





11 Example 


This FORTRAN-PLUS fragment takes a ‘black and white’ logical matrix (a chess board 
pattern) as input and returns the east boundary. 


ENTRY SUBROUTINE ENT 
LOGICAL LM(,),KM(,) 

EXTERNAL LOGICAL MATRIX FUNCTION XO5_EAST_BOUNDARY 
LM=ALTR(1).LEQ.ALTC(1) 
KM=X05_EAST_BOUNDARY (LM) 

TRACE 1 (KM) 

RETURN 

END 


The result in this case is simply LM .AND. COLS(31,32) 
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Purpose 


X05_E._MAX-_PC returns a logical matrix marking the maximum value(s) in each row of the 
real matrix argument. The i** row of the argument contains one or more elements whose 
value is the maximum value for the row. The corresponding element(s) of the i?” row of the 
logical matrix are set to .TRUE. to mark that maximum value, with all other elements of 
the logical matrix set to .FALSE. 


Specification 


LOGICAL MATRIX FUNCTION X05_E.MAX_PC(RM) 
REAL RM(,) 


Description 


In each row of the argument which contains at least one positive number the position(s) of the 
maximum positive number is found, and the corresponding output logical mask element(s) 
set to . TRUE. If a row of the argument contains only negative numbers, the position(s) of 
the elements with smallest absolute value are found, and the corresponding logical mask 
elements set to .TRUE.,; all other elements of the output mask are set to FALSE. 


References 


None 


Arguments 
RM — REAL MATRIX 


On entry, RM contains the matrix whose row-wise maximum positions are required. RM 
is unchanged on exit. 


Error Indicators 


None 


Auxiliary Routines 


None 


Accuracy 
Not applicable 


Further Comments 


None 


Keywords 


Maximum 


Example 


In each row of the matrix processed in the following FORTRAN-PLUS fragment the maxi- 
mum value(s) in that row are replaced by the value 0.0. 
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SUBROUTINE EXAMPLE(RM) 
REAL RM(,) 
LOGICAL LM(,) 


EXTERNAL LOGICAL MATRIX FUNCTION XO5_E_MAX_PC 
LM = XO5_E_MAX_PC(RM) 
RM(LM) = 0.0 


RETURN 
END 
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Purpose 


X05. E.MAX_PR returns a logical matrix marking the maximum value(s) in each column 
of the real matrix argument. The #* column of the argument contains one or more elements 
whose value is the maximum value for the column. The corresponding element(s) of the i** 
column of the logical matrix are set to .TRUE. to mark that maximum value, with all other 
elements of the logical matrix set to .FALSE. 


Specification 


LOGICAL MATRIX FUNCTION X05.E.MAX_PR (RM) 
REAL RM(,) 


Description 


In each column of the argument which contains at least one positive number the position(s) 
of the maximum positive number is found, and the corresponding output logical mask el- 
ement(s) set to .TRUE. If a column of the argument contains only negative numbers, the 
position(s) of the elements with smallest absolute value are found, and the corresponding 
logical mask elements set to .TRUE.,; all other elements of the output mask are set to .FALSE. 


References 
None 


Arguments 
RM - REAL MATRIX 


On entry, RM contains the matrix whose column-wise maximum positions are required. 
RM is unchanged on exit. 


Error Indicators 


None 


Auxiliary Routines 


None 


Accuracy 
Not applicable 


Further Comments 


None 


Keywords 


Maximum 


Example 


In each column of the matrix input to the following FORTRAN-PLUS fragment the maxi- 
mum values(s) in that column are replaced by the value 0.0. 
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SUBROUTINE EXAMPLE(RM) 
REAL RM(,) 
LOGICAL LM(,) 


EXTERNAL LOGICAL MATRIX FUNCTION XO5_E_MAX_PR 
LM = XO5_E_MAX_PR(RM) 
RM(LM) = 0.0 


RETURN 
END 
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X05 — Other utilities 


AMT 

















X05 — Other utilities 15.6 X05.E.MAX_VC 


15.6 X05_E_MAX _VC release 1 


10 


11 


Purpose 


X05.E.MAX_VC returns a real vector whose i** component is the maximum value in the 
i** row of the real matrix argument. ~ 


Specification 


REAL VECTOR FUNCTION X05. E.MAX-VC(RM) 
REAL RM(,) 


Description 


The maximum values are found by locating the position(s) of the maximum value in each 
row and then taking the value in the first of these positions in each row. These maximum 
values are then used to construct the required output vector. 


References 


None 


Arguments 
RM — REAL MATRIX 


On entry, RM contains the matrix whose row-wise maximum values are required. RM is 
unchanged on exit. : 


Error Indicators 


None 


Auxiliary Routines 


The routine calls the routines XO5.WEST. BOUNDARY and X05_E.MAX-_PC from the 
General Support library. 


Accuracy 
Not applicable 


Further Comments 


None 


Keywords 


Maximum 


Example 


In each row of the real matrix input to the following FORTRAN-PLUS fragment the maxi- 
mum value in the row is subtracted from all the values in the row. 
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SUBROUTINE EXAMPLE(RM) 
REAL RM(,) 


EXTERNAL REAL VECTOR FUNCTION XO5_E_MAX_VC 
RM=RM - MATC(XO5_E_MAX_VC(RM)) 


RETURN 
END 
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X05 — Other utilities 15.7 X05.E.MANX_V 
15.7 X05_E_MAX VR : release 1 
1 Purpose 
X05_E.MAX_VR returns a real vector whose i** component is the maximum value in the 
i*® column of the real matrix argument. 
2 Specification 
REAL VECTOR FUNCTION X05_.E.MAX.VR(RM) 
REAL RM(,) ; 
3 Description 
The maximum values are found by locating the position(s) of the maximum value in each 
column and then taking the value in the first of these position(s) in each column. These 
maximum values are then used to construct the required output vector. 
4 References 
None 
5 Arguments 
RM - REAL MATRIX 
On entry, RM contains the matrix whose column-wise maximum values are required. 
RM is unchanged on exit. 
6 Error Indicators 
None 
7 Auxiliary Routines 
The routine calls the routines X05.E.MAX_PR and X05. NORTH_BOUNDARY from the 
General Support library. 
8 Accuracy 
Not applicable 
9 Further Comments 
None 
10 Keywords 
Maximum 
11 Example 


In each column of the real matrix input to the following FORTRAN-PLUS fragment the 
maximum value in the column is subtracted from all the values in the column. 
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SUBROUTINE EXAMPLE(RM) 
REAL RM(,) 


EXTERNAL REAL VECTOR FUNCTION XO5_E_MAX_VR 
RM=RM - MATR(XO5_E_MAX_VR(RM) ) 


RETURN 
END 
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Other utilities 15.8 X05. E_.MIN_PC 


15.8 X05_E_MIN _PC release 1 


10 


11 


Purpose 


X05_E_MIN _PC returns a logical matrix marking the minimum value(s) in each row of the 
real matrix argument. The i** row of the argument contains one or more elements whose 
value is the minimum value for the row. The corresponding element(s) of the i** row of the 
logical matrix are set to .TRUE. to mark that minimum value, with all other elements of 
the logical matrix set to .FALSE. 


Specification 


LOGICAL MATRIX FUNCTION X05. E.MIN_PC(RM) 
REAL RM(,) 


Description 


In each row of the argument which contains only positive numbers the position(s) of the 
minimum number is found, and the corresponding output logical mask element(s) set to 
-TRUE. If a row of the argument contains at least one negative number, the position(s) of 
the negative number with greatest absolute value are found, and the corresponding logical 
mask elements set to .TRUE.; all other elements of the output mask are set to .FALSE. 


References 


None 


Arguments 
RM — REAL MATRIX 


On entry, RM contains the matrix whose row-wise minimum positions are required. RM 
is unchanged on exit. 


Error Indicators 


None 


Auxiliary Routines 
None 


Accuracy 
Not applicable 


Further Comments 


None 
Keywords 
Minimum 


Example 


In each row of the matrix input to the following FORTRAN-PLUS fragment the minimum 
value(s) in that row are replaced by the value 0.0. 
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15.8 X05.E._.MIN_PC X05 — Other utilities 


SUBROUTINE EXAMPLE (RM) 
REAL RM(,) 
LOGICAL LM(,) 





EXTERNAL LOGICAL MATRIX FUNCTION X05_E_MIN_PC 


LM = XO5_E_MIN_PC(RM) 
RM(LM) = 0.0 

RETURN 

END 
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X05 — 


Other utilities 15.9 X05.E_MIN_PR 


15.9 X05_E_MIN _PR release 1 


10 


11 


Purpose 


X05. E_MIN ~PR returns a logical matrix marking the minimum value(s) in each column of 
the real matrix argument. The i** column of the argument contains one or more elements 
whose value is the minimum value for the column. The corresponding element(s) of the it” 
column of the logical matrix are set to .TRUE. to mark that minimum value, with all other 
elements of the logical matrix set to .FALSE. 


Specification 


LOGICAL MATRIX FUNCTION X05_E.MIN_PR(RM) 
REAL RM(,) 


Description 


In each argument column which contains only positive numbers the position(s) of the mini- 
mum number is found, and the corresponding output logical mask element(s) set to .TRUE. 
If a column of the argument contains at least one negative number, the position(s) of the 
negative number with greatest absolute value are found, and the eoeresponding logical mask 
elements set to .TRUE.; all other elements of the output mask are set to FALSE. 


References 
None 


Arguments 
RM ~ REAL MATRIX 


On entry, RM contains the matrix whose column-wise minimum positions are required. 
RM is unchanged on exit. 


Error Indicators 


None 


Auxiliary Routines 


None 


Accuracy 
Not applicable 


Further Comments 


None 


Keywords 


Minimum 


Example 


In each column of the matrix input to the following FORTRAN-PLUS fragment the minimum 
value(s) in that column are replaced by the value 0.0. 
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SUBROUTINE EXAMPLE(RM) 
REAL RM(,) 
LOGICAL LM(,) 


EXTERNAL LOGICAL MATRIX FUNCTION XO5_E_MIN_PR 
LM=X05_E_MIN_PR(RM) 
RM(LM)=0.0 


RETURN 
END 
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X05 - Other utilities 15.10 X05.E_MIN_VC 
15.10 X05_E_MIN_VC release 1 
1 Purpose 
X05.E.MIN _VC returns a real vector whose i** component is the minimum value in the i¢* 
row of the real matrix argument. 
2 Specification 
REAL VECTOR FUNCTION X05_E_MIN .VC(RM) 
REAL RM(,) 
3 Description 
The minimum values are found by locating the positions of the minimum values in each row 
and then taking the value in the first of these positions in each row. The minimum values 
so found are used to construct the output vector. 
4 References 
None 
5 Arguments 
RM - REAL MATRIX 
On entry, RM contains the matrix whose row-wise minimum values are required. RM is 
unchanged on exit. ; , 
6 Error Indicators 
None 
7 Auxiliary Routines 
The routine calls the routines X05.E.MIN_PC and X05.WEST. BOUNDARY from the 
General Support library. 
8 Accuracy 
Not applicable 
9 Further Comments 
None 
10 Keywords 
Minimum 
11 Example 


In each row of the real matrix input to the following FORTRAN-PLUS fragment the mini- 
mum value in the row is subtracted from all the values in the row. 
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SUBROUTINE EXAMPLE (RM) 
REAL RM(,) 


EXTERNAL REAL VECTOR FUNCTION XO5_E_MIN_VC 
RM = RM-~- MATC(XO5_E_MIN_VC(RM) ) 


RETURN 
END 
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X05 — Other utilities 15.11 X05_E. MIN -VR 
15.11 X05_E_MIN _VR release 1 
1 Purpose 
X05_E_MIN .VR returns a real vector whose i** component is the minimum value in the i?” 
column of the real matrix argument. 
2 Specification 
REAL VECTOR FUNCTION X05_E_MIN _VR(RM) 
REAL RM(,) 
3 Description 
The minimum values are found by locating the positions of the minimum values in each 
column and then taking the value in the first of these positions in each column. The minimum 
values so found are used to construct the output vector. 
4 References 
None 
5 Arguments 
RM ~ REAL MATRIX 
On entry, RM contains the matrix whose column-wise minimum values are educa RM 
is unchanged on exit. 
6 Error Indicators 
None 
7 Auxiliary Routines 
The routine calls the routines X05.E.MIN _PR and X05.NORTH. BOUNDARY from the 
General Support library. 
8 Accuracy 
Not applicable 
9 Further Comments 
None 
10 Keywords 
Minimum 
11 Example 


In each column of the real matrix input to the following FORTRAN-PLUS fragment the 
minimum value in the column is subtracted from all the values in the column. 


General Support library man010.02 231 


15.11 X05.E.MIN_VR 
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SUBROUTINE EXAMPLE(RM) 
REAL RM(,) 


EXTERNAL REAL VECTOR FUNCTION XO5_E_MIN_VR 
RM = RM — MATR(XO5_E_MIN_VR(RM) ) 


RETURN 
END 
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X05 — Other utilities 15.12 X05. EXCH_P 


15.12 X05_EXCH_P release 1 





1 Purpose 


X05. EXCH _P exchanges L planes starting at X with L planes starting at Y, under activity 
control specified by M. The planes are exchanged in increasing order; you are cautioned 
about the strange effects which will occur if the two sets of planes overlap. 


2 Specification 


SUBROUTINE X05_EXCH.P(X ,Y,M,L) 
INTEGER L 

LOGICAL M (,) 

<any type> X(,), Y(,) 


3 Description 


The areas are exchanged under activity control using a machine code loop. 


4 References 


None 


5 Arguments 


X — <any type> MATRIX (or MATRIX array) 
On entry, X contains the data to be exchanged with Y. On exit, X contains the data 
© originally held in Y. 
Y - <any type> MATRIX (or MATRIX array) 


On entry, Y contains the data to be exchanged with X. On exit, Y contains the data 
originally held in X. 


M -— LOGICAL MATRIX 


On entry, M defines the mask; .TRUE. indicates elements to be exchanged. M is un- 
changed on exit. 


L ~ INTEGER 


On entry, L specifies the number of planes to be exchanged and must be less than the 
maximum number of times that a machine code DO-loop may be executed (23° times on 
the DAP 500). L is unchanged on exit. 


6 Error Indicators 


None 


7 Auxiliary Routines 


None 


8 Accuracy 
Not applicable 
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15.12 X05.EXCH_P X05 — Other utilities 


9 Further Comments 





None 


10 Keywords 


Data exchange, planar exchange 


11 Example 


This FORTRAN-PLUS fragment shows how the routine could be used to exchange two one 
byte matrices. 


ENTRY SUBROUTINE SWAP 
INTEGER*1 A(,),B(,) 

A = 13 

B = 25 

CALL XO5_EXCH_P(A,B,MAT(.TRUE.) ,8) 
TRACE 1 (A, B) 

RETURN 

END 


Results 


FORTRAN-PLUS Trace 
FORTRAN-PLUS Subroutine: SWAP at Line 8 





Integer Matrix Local Variable A in 8 bits - addressed by Stack + 0.09 


(Row 01 Col 01) 25 (* 32) 
(Row 02 Col 01) 25 (* 32) 
(Row 03 Col 01) 25 (* 32) 


(Row 30 Col 01) 25 (* 32) 
(Row 31 Col 01) 25 (* 32) 
(Row 32 Col 01) 25 (* 32) 


Integer Matrix Local Variable B in 8 bits - addressed by Stack + 0.10 
(Row 01 Col 01) 13 (* 32) 


(Row 02 Col 01) 13 (* 32) 
(Row 03 Col 01) 13 (* 32) 
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(Row 30 Col 01) 13 (* 32) 
(Row 31 Col O01) 13 (* 32) 
(Row 32 Col 01) 13 (* 32) 





End of Report 
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15.13 X05_GATHER_V_32 release 1 


1 Purpose 


236 


X05.GATHER.V-_32 assigns to the components of a vector the values of those components 
of a vector array designated by corresponding components of an indexing vector. The index 
values are interpreted as reduced rank indices to the vector array. 


Specification 
SUBROUTINE X05_GATHER_V_32(TO , FROM , NFROM , SELECT , IFAIL) 


TO and FROM must agree in type and length. They may be INTEGER* < 1—4>, 
REAL* < 3—4 > or CHARACTER. For example: 


INTEGER TO() , FROM(, NFROM) 
INTEGER NFROM , SELECT() , IFAIL 


Description 


The gathering is performed in a machine code DO loop. 


References 


None 


Arguments 


TO ~ INTEGER* < 1—4>, REAL* <3—4> or CHARACTER VECTOR 


On exit, TO contains 32 values from array FROM, as selected by SELECT; 
that is, TO (I) = FROM (SELECT (I)) for I = 1, 32 


FROM - INTEGER, REAL or CHARACTER VECTOR array 


The dimensions of the array are (,NFROM), agreeing with TO in type and length. 
FROM is unchanged on exit. 


NFROM - INTEGER 
The second dimension of array FROM. NFROM is unchanged on exit 


SELECT - INTEGER VECTOR 


The values are applied as reduced rank indices to array FROM to select values to be 
assigned to corresponding components of TO. SELECT is unchanged on exit. 


IFAIL - INTEGER 


Unless the routine detects an error (see Error indicators below) IFAIL contains zero 
on exit. 


Error Indicators 


Errors detected by the routine: 


IFAIL = 1 NFROM was not positive 


IFAIL = 2 Values of SELECT were not in range 1 to 32 NFROM 
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7 Auxiliary Routines 





None 


8 Accuracy 
Not applicable 


9 Further Comments 


None 


10 Keywords 


Data manipulation, gather, scatter 


11 Example 


This FORTRAN-PLUS fragment gathers alternate indexed elements of a 64 element vector 
into a 32 element vector. 


ENTRY SUBROUTINE ENT 
INTEGER FROM(,2),TO() ,SELECT() 
DO 10 I=1,64 
10 FROM(I)=10«I 
DO 20 I=1,32 


20 SELECT(I)=2+I1 
© CALL X05_GATHER_V32(TO,FROM,2,SELECT, IFAIL) 
TRACE 1 (IFAIL) 
TRACE 1 (TO) 
RETURN 
END 


Results 


FORTRAN-PLUS Trace 
FORTRAN-PLUS Subroutine: ENT at Line 8 


Integer Scalar Local Variable IFAIL in 32 bits - on Stack at 0.13 
0 


End of Report 
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FORTRAN-PLUS Trace 
FORTRAN-PLUS Subroutine: ENT at Line 9 





Integer Vector Local Variable TO in 32 bits - addressed by Stack + 0.10 


(Component 01) 20, 40, 60, 80, 
(Component 05) 100, 120, 140, 160, 
(Component 09) 180, 200, 220, 240, 
(Component 13) 260, 280, 300, 320, 
(Component 17) 340, 360, 380, 400, 
(Component 21) 420, 440, 460, 480, 
(Component 25) 500, 520, 540, 560, 
(Component 29) 580, 600, 620, 640 


End of Report 
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X05 — Other utilities 15.14 X05_.I. MAX_.PC 


15.14 X05_I _MAX_PC release 1 


10 


Purpose 


X05-I.MAX-.PC returns a logical matrix marking the maximum value(s) in each row of the 
integer matrix argument. The i** row of the argument contains one or more elements whose 
value is the maximum value for the row. The corresponding element(s) of the i*” row of the 
logical matrix are set to .TRUE. to mark that maximum value, with all other elements of 
the logical matrix set to .FALSE. 


Specification 
LOGICAL MATRIX FUNCTION X05_I_.MAX_PC (IM , N) 
INTEGER* <N>IM (,) 
INTEGER N 

Description 


In each row of the argument which contains at least one positive number the position(s) of the 
maximum positive number is found, and the corresponding output logical mask element(s) 
set to .TRUE. If a row of the argument contains only negative numbers, the position(s) of 
the elements with smallest absolute value are found, and the corresponding logical mask 
elements set to .TRUE.; all other elements of the output mask are set to FALSE. 


References 


None 


Arguments 
IM - INTEGER* <N> MATRIX 


On entry, IM contains the matrix whose row-wise maximum positions are required. IM 
is unchanged on exit. 


N - INTEGER 
On entry, N specifies the length of the matrix IM in bytes. N is unchanged on exit. 


Error Indicators 


None 


Auxiliary Routines 


None 


Accuracy 
Not applicable 


Further Comments 


None 


Keywords 


Maximum 
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15.14 X05.I. MAX. PC X05 - Other utilities 


11 Example 


In each row of the matrix input to the following FORTRAN-PLUS fragment the maximum 
value(s) in that row are set to zero. 


SUBROUTINE EXAMPLE(IM) 
INTEGER*2 IM(,) 
LOGICAL LM(,) 


EXTERNAL LOGICAL MATRIX FUNCTION XO5_I_MAX_PC 
LM=X05_I_MAX_PC(IM, 2) 
IM(LM)=0 


RETURN 
END 
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X05 — Other utilities 15.15 X05_I. MAX. PR 
15.15 X05_I_.MAX_PR release 1 
1 Purpose 
X05_I_MAX_PR returns a logical matrix marking the maximum value(s) in each column of 
the integer matrix argument. The z** column of the argument contains one or more elements 
whose value is the maximum value for the column. The corresponding element(s) of the i** 
column of the logical matrix are set to .TRUE. to mark that maximum value, with all other 
elements of the logical matrix set to .FALSE. 
2 Specification 
LOGICAL MATRIX FUNCTION X05_I_MAX_PR(IM , N) 
INTEGER* <N>. IM (,) 
INTEGER N 
3 Description 
In each argument column which contains at least one positive number the position(s) of the 
maximum positive number is found, and the corresponding output logical mask element(s) 
set to .TRUE. If a column of the argument contains only negative numbers, the position(s) 
of the elements with smallest absolute value are found, and the corresponding logical mask 
elements set to :TRUE,; all other elements of the output mask are set to .FALSE. 
4 References 
None 
5 Arguments 
IM ~- INTEGER* <N> MATRIX 
On entry, IM contains the matrix whose column-wise maximum positions are required. 
IM is unchanged on exit. 
N - INTEGER 
On entry, N specifies the length of the matrix IM in bytes. N is unchanged on exit. 
6 Error Indicators 
None 
7 Auxiliary Routines 
None 
8 Accuracy 
Not applicable 
9 Further Comments 
None 
10 Keywords 
Maximum 
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11 Example 


In each column of the matrix input to the following FORTRAN-PLUS fragment the maxi- 
mum value(s) in that column are set to zero. 


SUBROUTINE EXAMPLE(IM) 
INTEGER*2 IM(,) 
LOGICAL LM(,) 


EXTERNAL LOGICAL MATRIX FUNCTION XO5_I_MAX_PR 
LM=X05_I_MAX_PR(IM, 2) 
IM(LM)=0 


RETURN 
END 
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15.16 X05_I __MAX_VC release 1 


10 


11 


Purpose 


X05_I.MAX_VC returns an integer vector whose i** component is the maximum value in 
the 7** row of the integer matrix argument. 


Specification 


INTEGER VECTOR FUNCTION X05.1-MAX_VC(IM) 
INTEGER IM (,) 


Description 


The maximum values are found by locating the positions of the maximum values in each row 
and then taking the value in the first of these positions in each row. These maximum values 
are then used to construct the required output vector. 


References 


None 


Arguments 
IM - INTEGER MATRIX 


On entry, IM contains the matrix whose row-wise maximum values are required. IM is 
unchanged on exit. 


Error Indicators 


None 


Auxiliary Routines 


The routine calls the routines X05.I. MAX_PC and X05.WEST_BOUNDARY from the 
General Support library. 


Accuracy 
Not applicable 


Further Comments 


None 


Keywords 


Maximum 


Example 


In each row of the integer matrix argument in this FORTRAN-PLUS fragment the maximum 
value in that row is subtracted from all the values in that row. 
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SUBROUTINE EXAMPLE(IM) 
INTEGER IM(,) 


EXTERNAL INTEGER VECTOR FUNCTION XO5_I_MAX_VC 
IM=IM-MATC(X05_I_MAX_VC(IM) ) 


RETURN 
END 
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15.17 X05_I _MAX_VR : release 1 


10 


11 


Purpose 


X05.1.MAX_VR returns an integer vector whose i** component is the maximum value in 
the i** column of the integer matrix argument. 


Specification 


INTEGER VECTOR FUNCTION X05_I_MAX_VR (IM) 
INTEGER IM (,) 


Description 


The maximum values are found by locating the positions of the maximum values in each 
column and then taking the value in the first of these positions in each column. These 
maximum values are then used to construct the required output vector. 


References 


None 


Arguments 
IM ~- INTEGER MATRIX 


On entry, IM contains the matrix whose column-wise maximum values are meqiured: IM 
is unchanged on exit. 


Error Indicators 


None 


Auxiliary Routines 


This routine calls the routines X05_I.MAX_PR and X05.NORTH. BOUNDARY fromthe 
General Support library. 


Accuracy 
Not applicable 


Further Comments 


None 


Keywords 


Maximum 


Example 


In each column of the integer matrix input to the following FORTRAN-PLUS fragment the 
maximum value in that column is subtracted from all the values in that column. 
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SUBROUTINE EXAMPLE(IM) 
INTEGER IM(,) 





EXTERNAL INTEGER VECTOR FUNCTION XO5_I_MAX_VR 


IM=IM-MATR(XO5_I_MAX_VR(IM)) 
RETURN 
END 
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Other utilities 15.18 X05.I_.MIN.PC 


15.18 X05_I_MIN_PC release 1 


10 


Purpose 


X05_I.MIN PC returns a logical matrix marking the minimum value(s) in each row of the 
integer matrix argument. The 7** row of the argument contains one or more elements whose 
value is the minimum value for the row. The corresponding element(s) of the i** row of the 
logical matrix are set to .TRUE. to mark that minimum value, with all other elements of 
the logical matrix set to .FALSE. 


Specification 
LOGICAL MATRIX FUNCTION X05_I_MIN_PC (IM , N) 
INTEGER* <N> IM(,) 
INTEGER N 

Description 


In each argument row which contains only positive numbers the position(s) of the minimum 
number is found, and the corresponding output logical mask element(s) set to .TRUE. If a 
row of the argument contains at least one negative number, the position(s) of the negative 
number with greatest absolute value are found, and the corresponding logical mask elements 
set to .TRUE.; all other elements of the output mask are set to .FALSE. 


References 


None 


Arguments 
IM ~ INTEGER* <N> MATRIX 


On entry, IM contains the matrix whose row-wise minimum positions are required. IM 
is unchanged on exit. 


N - INTEGER 
On entry, N specifies the length of the matrix IM in bytes. N is unchanged on exit. 


Error Indicators 


None 


Auxiliary Routines 


None 


Accuracy 
Not applicable 


Further Comments 
None 


Keywords 


Minimum 
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11 Example 





In each row of the matrix input to the following FORTRAN-PLUS fragment the minimum 
value(s) in that row are set to zero. 


SUBROUTINE EXAMPLE(IM) 
INTEGER*2 IM(,) 
LOGICAL LM(,) 


EXTERNAL LOGICAL MATRIX FUNCTION XO5_I_MIN_PC 


LM=X05_I_MIN_PC(IM, 2) 
IM(LM)=0 

RETURN 

END 
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15.19 X05_I_MIN_PR release 1 


10 


Purpose 


X05.I_MIN _PR returns a logical matrix marking the minimum value(s) in each column of 
the integer matrix argument. The i** column of the argument contains one or more elements 
whose value is the minimum value for the column. The corresponding element(s) of the i** 
column of the logical matrix are set to .TRUE. to mark that minimum value, with all other 
elements of the logical matrix set to .FALSE. 


Specification 


LOGICAL MATRIX FUNCTION X05_I_MIN_PR(IM , N) 
INTEGER* <N> IM(,) 
INTEGER N 


Description 


In each argument column which contains only positive numbers the position(s) of the mini- 
mum number is found, and the corresponding output logical mask element(s) set to . TRUE. 
If a column of the argument contains at least one negative number, the position(s) of the 
negative number with greatest absolute value are found, and the corresponding logical mask 
elements set to .TRUE.; all other elements of the output mask are set to FALSE. 


References 


None 


Arguments 
IM ~ INTEGER* <N> MATRIX 


On entry, IM contains the matrix whose column-wise minimum positions are required. 
IM is unchanged on exit. 


N - INTEGER 
On entry, N specifies the length of the matrix IM in bytes. N is unchanged on exit. 


Error Indicators 


None 


Auxiliary Routines 


None 


Accuracy 
Not applicable 


Further Comments 


None 


Keywords 


Minimum 
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11 Example 


In each column of the input matrix in this FORTRAN-PLUS fragment the minimum value(s) 
in that column are set to zero. 


SUBROUTINE EXAMPLE(IM) 
INTEGER*2 IM(,) 
LOGICAL LM(,) 


EXTERNAL LOGICAL MATRIX FUNCTION XO5_I_MIN_PR 
LM=X05_I_MIN_PR(IM, 2) 
IM(LM)=0 


RETURN 
END 
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15.20 X05_I_ MIN _VC release 1 


10 


11 


Purpose 


X05_I_MIN VC returns an integer vector whose i‘* component is the minimum value in the 
it row of the integer matrix argument. 


Specification 


INTEGER VECTOR FUNCTION X05_I.MIN -VC(IM) 
INTEGER IM (,) 


Description 


The minimum values are found by locating the positions of the minimum values in each row 
and then taking the value in the first of these positions in each row. The minimum values 
so found are used to construct the output vector. 


References 


None 


Arguments 
IM - INTEGER MATRIX 


On entry, IM contains the matrix whose row-wise minimum values are required. IM is 
unchanged on exit. 


Error Indicators 
None 


Auxiliary Routines 


The routine calls routines X05.I. MIN _PC and X05_WEST.BOUNDARY from the General 
Support library. 


Accuracy 
Not applicable 


Further Comments 
None 


Keywords 


Minimum 


Example 


In each row of the integer matrix input to the following FORTRAN-PLUS fragment the 
minimum value in that row is subtracted from all the values in that row. 
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SUBROUTINE EXAMPLE(IM) 
INTEGER IM(,) 





EXTERNAL INTEGER VECTOR FUNCTION XO5_I_MIN_VC 


IM=IM-MATC(XO5_I_MIN_VC(IM)) 
RETURN 
END 
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Purpose 


X05_I_MIN _VR returns an integer vector whose i” component is the minimum value in the 
» column of the integer matrix argument. 


Specification 


INTEGER VECTOR FUNCTION X05_I_MIN_VR aM) 
INTEGER IM (,) 


Description 


The minimum values are found by locating the positions of the minimum values in each 
column and then taking the value in the first of these positions in each column. The minimum 
values so found are used to construct the output vector. 


References 


None 


Arguments 
IM - INTEGER MATRIX 


On entry, IM contains the matrix whose column-wise minimum values are reqUESE IM 
is unchanged on exit. 


Error Indicators 
None 


Auxiliary Routines 
The routine calls the General Support library routines X05_I_ MIN _PR and X05_NORTH _BOUNDARY. 


Accuracy 
Not applicable 


Further Comments 


None 


Keywords 


Minimum 


Example 


In each column of the integer matrix input to the following FORTRAN-PLUS fragment the 
minimum value in that column is subtracted from all the values in the column. 
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SUBROUTINE EXAMPLE(IM) 
INTEGER IM(,) 


EXTERNAL INTEGER VECTOR FUNCTION XO5_I_MIN_VR 
IM=IM-MATR(XO5_I_MIN_VR(IM)) 


RETURN 
END 


man010.02 


X05 — Other utilities 


AMT 

















X05 — Other utilities 15.22 X05. LOG2 


15.22 X05_ LOG2 release 1 


1 Purpose 


X05_LOG2 returns the number of steps required in a recursive doubling algorithm. 


2 Specification 
INTEGER FUNCTION X05_LOG2(N) 
INTEGER N 
3 Description 
The value returned by the routine is: 
[logy(N—1)]+1 
where square brackets indicate ‘integer part of’, and N is the input argument. 


The routine subtracts 1 from N, then scans the bit pattern of N — 1 serially, starting at 
the most significant bit, to find the first .TRUE. bit. The required output value equals 
(11 - the number of serial steps taken). 


For N greater than 1024, X05_LOG2 returns an incorrect value, as the routine takes (N 
modulo 1024) as its argument. 


4 References 
None 


5 Arguments 


N - INTEGER 


On entry, the value in N should lie in the range 1 — 1024. N = 0 will return the result 
10; for N < 0 the result is undefined. N is unchanged on exit. 


6 Error Indicators 


None 


7 Auxiliary Routines 
None 


8 Accuracy 
Not applicable 


9 Further Comments 


None 


10 Keywords 


Logarithmic algorithm, recursive doubling 
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Example 


X05 — Other utilities 


The example calculates the number of steps required by a recursive doubling algorithm for 


a problem of size 1001. 


Host program 


PROGRAM MAIN 
INTEGER N,LOG2N 
COMMON /LOG2N/ N,LOG2N 


Cc 
C Initialise data for function 
Cc 
N = 1001 
Cc 
C Connect to DAP module 
c 
CALL DAPCON(’ ent.dd’) 
Cc 
C Send test data to the DAP 
Cc 
CALL DAPSEN(’?LOG2N’ ,N,1) 
Cc 
C Call the DAP ENTRY subroutine 
Cc 
CALL DAPENT(’ENT?’) 
C Send test data and result from the DAP 
C 
CALL DAPREC(’LOG2N? ,N,2) 
Cc 
C Release the DAP 
C 
CALL DAPREL 
Cc 


C Write out the data and result for inspection. 


WRITE(6,1) N,LOG2N 

1 FORMAT( ’?VALUE OF N = ’?,I6/’STEPS REQUIRED = ’,16) 
STOP 
END 


DAP program 


ENTRY SUBROUTINE ENT 

INTEGER N,LOG2N 

COMMON /LOG2N/ N,LOG2N 
Cc 
C Note the EXTERNAL statement for this function 
Cc 

EXTERNAL INTEGER SCALAR FUNCTION X05_LOG2 
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Cc 
C Convert input data 
Cc 





CALL CONVFSI(N, 1) 

LOG2N = X05_L0G2(N) 
c 
C Convert input data and results back to host format 
Cc 

CALL CONVSFI(N,2) 

RETURN 

END 


Results 


VALUE OF N = 1001 
STEPS REQUIRED = 10 





General Support library man010.02 257 








15.23 X05. LONG. INDEX X05 ~ Other utilities 


15.23 X05_LONG_INDEX release 1 
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Purpose 


X05. LONG_INDEX generates an integer matrix whose i*” element in long vector order is 
(i + N - 1), where N is a parameter to the routine. 


Specification 
SUBROUTINE X05. LONG_INDEX (IMAT , N) 
INTEGER IMAT(,) ,N 

Description 


The routine calls the FORTRAN-PLUS intrinsic ‘Long_ Index’, and is provided for backwards 
compatability with existing code. 


References 


None 


Arguments 
IMAT - INTEGER MATRIX 


On exit, the i** component in long vector order of IMAT will contain (i + N - 1). 


N - INTEGER 
On entry, N specifies the value that is required in IMAT (1). N is unchanged on exit. 


Error Indicators 


None 


Auxiliary Routines 


None 


Accuracy 
Not applicable 


Further Comments 


Overflow is not detected for large values of N. 


Keywords 


Indexing 


Example 


The example generates a vector indexed from 1 to 1024. 
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Host program 


PROGRAM MAIN 
INTEGER IM(32,32) 
COMMON /IM/IM 
CALL DAPCON(’ ent.dd’) 
CALL DAPENT(’? ENT?) 
CALL DAPREC(? IM? , IM, 1024) 
CALL DAPREL 
DO 10 I=1,32 
DO 10 J=1,32 
10 WRITE(6,1000) IM(J,I) 
1000 FORMAT(1X,I6) 
STOP 
END 


DAP program 


ENTRY SUBROUTINE ENT 
INTEGER IM(,) 

COMMON /IM/IM 

CALL XO5_LONG_INDEX (IM, 1) 
CALL CONVMFI(IM) 

RETURN 

END 


Results 


noe 


1024 
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Purpose 


X05. NORTH BOUNDARY returns a logical matrix containing at most one .TRUE. in 
each column corresponding to the first .TRUE. (if any) in each column of the logical matrix 
parameter. That is, the routine is equivalent to the FORTRAN-PLUS code: 


KM = -FALSE. 
DO 101 = 1,32 
IF (.NOT. ANY (LM(,I))) GOTO 10 
KM (,I) = FRST (LM (,1)) 

10 CONTINUE 


Specification 


LOGICAL MATRIX FUNCTION X05. NORTH BOUNDARY (LM) 
LOGICAL LM (,) 


Description 


The DAP store plane (logical matrix LM) passed to the routine is treated as a set of 32 
logical vectors, arranged so that each vector occupies a complete column. Each of these 
vectors is dealt with independently, but in parallel. 


To each vector is ripple-added a column of all-true bits; the northernmost bit of the vector 
is treated as least significant. The addition column is thrown away; the column of carry bits 


‘from the addition, and a shifted-south version of the column of carries, are XORed to give a 


vector with only one true element: the northernmost .TRUE. element in each input vector. 
The 32 resultant vectors, produced in parallel, form the required north boundary matrix. 


References 


None 


Arguments 
LM — LOGICAL MATRIX 


On entry, LM is the logical matrix whose north boundary is required. LM is unchanged 
on exit. 


Error Indicators 


None 


Auxiliary Routines 


None 


Accuracy 
Not applicable 


Further Comments 


None 
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10 Keywords 





Boundary 


11 Example 


The following FORTRAN-PLUS fragment takes a ‘black and white’ logical matrix (a chess 
board pattern) as input, and returns the north boundary. 


ENTRY SUBROUTINE ENT 
LOGICAL LM(,),KM(,) 

EXTERNAL LOGICAL MATRIX FUNCTION XO5_NORTH_BOUNDARY 
LM=ALTR(1).LEQ.ALTC(1) | 

KM=X05_NORTH_BOUNDARY (LM) 

TRACE 1 (KM) 

RETURN 

END 


The result in this case is simply LM .AND. ROWS (1, 2) 
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Purpose 


X05_ PATTERN produces four user-selectable patterns, each of which is returned as a logical 
matrix. The four patterns available are: 


0 — The main diagonal 

1 — The minor diagonal 

2 — A matrix, the rows of which correspond to the rows generated by the built-in 
function ALTC 

3 — The unit lower triangular matrix 


Specification 
LOGICAL MATRIX FUNCTION X05. PATTERN (I) 
INTEGER I 

Description 


The routine is provided for backwards compatability with existing code. 


References 
None 
Arguments 
I - INTEGER 
On entry I specifies the pattern required. Four values are catered for: 
I=0: RESULT(J,J) = .TRUE. where 0 < J < 33; all other elements are 
.FALSE. 
I=1: RESULT(J,33-J) = .TRUE. where 0 < J < 33; all other elements are 
.FALSE. 
I= 2 : RESULTV(J,) is set equal to the row which generates ALTC (J - 1) 
I= 3: RESULT(J,K) = .TRUE. if J.GE.K where 0< J, K < 33 
I is unchanged on exit. 
Error Indicators 


IfI <0 orI > 3 X05. PATTERN returns a logical matrix with all entries FALSE. 


Auxiliary Routines 


None 


Accuracy 
Not applicable 
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9 Further Comments 





None 


10 Keywords 


Pattern generation 


11 Example 


In the following FORTRAN-PLUS fragment the patterns produced by the routine are used 
to set up an integer identity matrix and a second matrix having 1 (. TRUE.) below the main 
diagonal and 0 (.FALSE.) everywhere else. 


ENTRY SUBROUTINE ENT 

INTEGER IDENT(,), LOWER(,) 

LOGICAL DIAG(,) 

EXTERNAL LOGICAL MATRIX FUNCTION XO5_PATTERN 
DIAG = XO5_PATTERN (0) 


IDENT = 0 

IDENT (DIAG) = 1 

LOWER = 0 
LOWER(XO5_PATTERN(3).AND..NOT.DIAG) = 1 
RETURN 

END 
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15.26 X05_SCATTER_V_32 release 1 


1 Purpose 


X05.SCATTER_V._32 takes components of.a vector and assigns the values to components 
of a vector array designated by corresponding components of an indexing vector. The index 
values are interpreted as reduced rank indices to the vector array. 


2 Specification 
SUBROUTINE X05_SCATTER_V_32(FROM , TO , NTO , SELECT , IFAIL) 


FROM and TO must agree in type and length. They may be INTEGER* <1~—4>, 
REAL* < 3—4> or CHARACTER. For example: 


INTEGER FROM() , TO(,NTO) 
INTEGER NTO , SELECT () , IFAIL 


3 Description 


The scattering is performed in a machine code DO loop. 


4 References 


None 


5 Arguments 
FROM — INTEGER* < 1-—4>, REAL* < 3—4> or CHARACTER VECTOR 


Contains the 32 values to be scattered; it is unchanged on exit. 


TO —- INTEGER, REAL or CHARACTER VECTOR array 


The dimensions of the array are (, NTO), agreeing with FROM in type and length. On 
exit, TO contains 32 values from FROM, as selected by SELECT; 
that is, TO (SELECT (I)) = FROM (1) for I = 1, 32 


NTO - INTEGER 


The second dimension of array TO; NTO is unchanged on exit 


SELECT - INTEGER VECTOR 


The values are applied as reduced rank indices to TO, to select components as destina- 
tions for corresponding values from array FROM. SELECT is unchanged on exit. 


IFAIL - INTEGER 


Unless the routine detects an error (see Error indicators below) IFAIL contains zero 
on exit. 


6 Error Indicators 
Errors detected by the routine: 
IFAIL = 1 NTO was not positive 


IFAIL = 2 Values of SELECT were not in range 1 to 32NTO 
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10 


11 


Auxiliary Routines 


None 


Accuracy 
Not applicable 


Further Comments 


None 


Keywords 


Data manipulation, gather, scatter 


Example 


The following FORTRAN-PLUS fragment scatters a 32 element vector to alternate positions 
in a 64 element vector. 


ENTRY SUBROUTINE ENT 
INTEGER FROM() ,TO(,2),SELECT() 
DO 10 I=1,64 
10 TO(I)=0 
DO 20 I=1,32 
FROM(I)=I 
20 SELECT(I)=2+I 
CALL XOS_SCATTER_V32(FROM,TO,2,SELECT, IFAIL) 
TRACE 1 (IFAIL) 
TRACE 1 (TO) 
RETURN 
END 


Results 


FORTRAN-PLUS Trace 
FORTRAN-PLUS Subroutine: ENT at Line 9 


Integer Scalar Local Variable IFAIL in 32 bits - on Stack at 0.13 
0 
End of Report 


FORTRAN-PLUS Trace 
FORTRAN-PLUS Subroutine: ENT at Line 10 


Integer Vector Local Variable TO in 32 bits - addressed by Stack + 0.10 
Unconstrained dimensions - 2 
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(Element 1) 





(Component 01) 0, 1, Oo, 2. 
(Component 05) 0, 3, 0, 4, 
(Component 09) 0, 5, 0, 6, 
(Component 13) 0, 7, 0, 8, 
(Component 17) 0, 9, Oo, 10, 
(Component 21) 0, 11, 0, 12, 
(Component 25) Oo, 13, Oo, 14, 
(Component 29) 0, 15, 0, 16 
(Element 2) 

(Component 01) 0, 17, 0, 18, 
(Component 05) 0, 19, 0, 20, 
(Component 09) Oo, 21, 0, 22, 
(Component 13) 0, 23, Oo, 24, 
(Component 17) 0, 25, 0, 26, 
(Component 21) Oo, 27, 0, 28, 
(Component 25) 0, 29, 0, 30, 
(Component 29) 0, 31, 0, 32 


End of Report 
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1 Purpose 


X05.SHLC_LV performs a cyclic long vector shift to the left on a number of bit planes, up 
to a maximum of 256 planes. 


2 Specification 


SUBROUTINE X05.SHLC_LV(V , W , DEPTH , DIST) 
INTEGER DEPTH , DIST 
LOGICAL V(,,DEPTH) , W(,, DEPTH) 


3 Description 


The shift is carried out in two stages. If the shift distance is D, then North/South shifting 
is used for that part of the shift given by D modulo 32, and a West shift is used to handle 
the remaining multiples of 32. 


4 References 


None 


‘5 Arguments 
V - LOGICAL MATRIX array of dimension (,, DEPTH) 
o) . On entry, V contains the data to be shifted; V is unchanged on exit. 


W - LOGICAL MATRIX array of dimension (,, DEPTH) 
On exit, W contains the shifted version of the data in V. 


DEPTH - INTEGER 


On entry, DEPTH specifies the dimension of V; that is, the number of planes to be 
shifted (taken modulo 256). DEPTH is unchanged on exit. 


DIST — INTEGER 
On entry, DIST specifies the magnitude of the shift (taken modulo 1024). DIST is 
unchanged on exit. 
6 Error Indicators 


None 


7 Auxiliary Routines 


None 


8 Accuracy 
Not applicable 


9 Further Comments 


None 





General Support library man010.02 267 








15.27 X05.SHLC_LV X05 — Other utilities 


10 Keywords 
Shifting 





11 Example 


The example compares the result from X05_SHLC_LV with that from the built-in function 
SHLC. The number of positions at which the two results disagree is counted and displayed. 


Host program 


PROGRAM MAIN 
COMMON /ICOUNT/ICOUNT 
CALL DAPCON(’ ent.dd’) 
CALL DAPENT(’ENT?) 
CALL DAPREC(’?ICOUNT? , ICOUNT, 1) 
CALL DAPREL 
WRITE(6,1000) ICOUNT 
1000 FORMAT(’ ICOUNT = ’,I5) 
STOP 
END 


DAP program 


ENTRY SUBROUTINE ENT 

INTEGER IM(,),JM(,),KM(,) 
COMMON /ICOUNT/ICOUNT 

CALL XO5_LONG_INDEX(IM, 1) 
CALL XOS_SHLC_LV(IM, JM,32,99) 
KM=SHLC(IM, 99) 

ICOUNT = SUM(KM.NE. JM) 

CALL CONVSFI(ICOUNT, 1) 

RETURN 

END 





Results 


ICOUNT = 0 
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1 Purpose 


X05.SHLP_LV performs a planar long vector shift to the left on a number of bit planes, up 
to a maximum of 256 planes. 


2 Specification 


SUBROUTINE X05.SHLP_LV(V , W , DEPTH , DIST) 
INTEGER DEPTH , DIST 
LOGICAL V(,, DEPTH) , W(,, DEPTH) 


3 Description 


The shift is carried out in two stages. If the shift distance is D, then North/South shifting 
is used for that part of the shift given by D modulo 32, and a West shift is used to handle 
the remaining multiples of 32. 


4 References 


None 


5 Arguments 
V - LOGICAL MATRIX array of dimension (, , DEPTH) 
@ On entry, V contains the data to be shifted; V is unchanged on exit. 


W - LOGICAL MATRIX array of dimension (,, DEPTH) 


On exit, W contains the shifted version of the data in V. 


DEPTH - INTEGER 


On entry, DEPTH specifies the dimension of V; that is, the number of planes to be 
shifted (taken modulo 256). DEPTH is unchanged on exit. 


DIST - INTEGER 


On entry DIST specifies the magnitude of the shift (taken modulo 1024). DIST is un- 
changed on exit. 


6 Error Indicators 


None 


7 Auxiliary Routines 


None 


8 Accuracy 
Not applicable 


9 Further Comments 


None 
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11 
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Example 
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The example compares the result from X05.SHLP_LV with that from the built-in function 
SHLP. The number of positions at which the two results disagree is counted and displayed. 


Host program 


1000 


PROGRAM MAIN 
COMMON /ICOUNT/ICOUNT 

CALL DAPCON(’ent.dd’) 

CALL DAPENT(’ENT? ) 

CALL DAPREC(’ICOUNT’ , ICOUNT, 1) 
CALL DAPREL 

WRITE(6,1000) ICOUNT 

FORMAT(? ICOUNT =’ ,I5) 

STOP 

END 


DAP program 


ENTRY SUBROUTINE ENT 

INTEGER IM(,),JM(,),KM(,) 
COMMON /ICOUNT/ICOUNT 

CALL XO5_LONG_INDEX(IM, 1) 
CALL XO5_SHLP_LV(IM, JM,32,99) 
KM=SHLP (IM, 99) 

ICOUNT = SUM(KM.NE. JM) 

CALL CONVSFI(ICOUNT, 1) 

RETURN 

END 


Results 


ICOUNT = 0 
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Purpose 


X05_SHORT_INDEX uses the FORTRAN-PLUS intrinsic routine ‘Short_Index’, and is pro- 
vided: for backwards compatibility. 


Specification 


SUBROUTINE X05_SHORT_INDEX (IVEC , N) 
INTEGER IVEC() , N 


Description 
The routine is based on the FORTRAN-PLUS intrinsic ‘Short_ Index’. 


References 


None 


Arguments 
IVEC ~ INTEGER VECTOR 
On exit, the i** component of IVEC will contain (i + N - 1). 


N - INTEGER : 
On entry, N specifies the value that is required in IVEC (1); N is unchanged on exit. 


Error Indicators 


None 


Auxiliary Routines 


None 


Accuracy 
Not applicable 


Further Comments 


Overflow is not detected for extremely large values in N. 


Keywords 


Indexing 


Example 


The example generates a vector indexed from 1 to 32. 
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Host program 





PROGRAM MAIN 
INTEGER IV(32) 
COMMON /IV/IV 
CALL DAPCON(’ ent.dd’) 
CALL DAPENT(’ ENT?) 
CALL DAPREC(’ IV’ ,IV,32) 
CALL DAPREL 
DO 10 I = 1,32 

10 WRITE (6,1000) IV(I) 

1000 FORMAT(1X, I6) 
STOP 
END 


DAP program 


ENTRY SUBROUTINE ENT 
INTEGER IV() 

COMMON /IV/IV ; 
CALL XO5_SHORT_INDEX_(IV, 1) 
CALL CONVVFI(IV,32,1) 
RETURN 

END 








Results 


Nye 


32 
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1 Purpose 


X05_SHRC. LV performs a cyclic long vector shift to the right on bit planes, up to a maxi- 
mum of 256 planes. 


2 Specification 


SUBROUTINE X05.SHRC_LV(V , W , DEPTH , DIST) 
INTEGER DEPTH , DIST 
LOGICAL V(,, DEPTH) , W(,, DEPTH) 


3 Description 


The shift is carried out in two stages. If the shift distance is D, then North/South shifting 
is used for that part of the shift given by D modulo 32, and an East shift is used to handle 
the remaining multiples of 32. 


4 References 


None 


5 Arguments 
V ~ LOGICAL MATRIX array of dimension (,, DEPTH) 
@ On entry, V contains the data to be shifted; V is unchanged on exit. 


W - LOGICAL MATRIX array of dimension (,, DEPTH) 
On exit, W contains the shifted version of the data in V. 


DEPTH - INTEGER 


On entry, DEPTH specifies the dimension of V; thgat is, the number of planes to be 
shifted (taken modulo 256). DEPTH is unchanged on exit. 


DIST ~ INTEGER 


On entry, DIST specifies the magnitude of the shift (taken modulo 1024). DIST is 
unchanged on exit. 


6 Error Indicators 


None 


7 Auxiliary Routines 


None 


8 Accuracy 
Not applicable 


9 Further Comments 


None 
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10 Keywords 
Shifting 


11 Example 


The example compares the result from X05.SHRC_LV with that from the built-in function 
SHRC. The number of positions at which the two results disagree is counted and displayed. 


Host program 


PROGRAM MAIN 
COMMON. /ICOUNT/ICOUNT 
CALL DAPCON(?’ ent.dd’) 
CALL DAPENT(’ENT? ) 
CALL DAPREC(?ICOUNT? , ICOUNT, 1) 
CALL DAPREL 
WRITE(6,1000) ICOUNT 
1000 FORMAT(’? ICOUNT =’,I5) 
STOP 
END 


DAP program 


ENTRY SUBROUTINE ENT 

INTEGER IM(,),JM(,),KM(,) 
COMMON /ICOUNT/ICOUNT 

CALL XO5_LONG_INDEX(IM, 1) 
CALL XO5_SHRC_LV(IM, JM,32,99) 
KM=SHRC(IM,99) 
ICOUNT=SUM(KM.NE. JM) 

CALL CONVSFI(ICOUNT, 1) 

RETURN 

END 


Results 


ICOUNT = 0 


274 _ man010.02 AMT 











X05 - Other utilities 15.31 X05.SHRP.LV 


15.31 X05_SHRP_LV release 1 





1 Purpose 


X05.SHRP_LV performs a planar long vector shift to the right on a number of bit planes, 
up to a maximum of 256 planes. 


2 Specification 


SUBROUTINE X05_SHRP_LV(V , W , DEPTH , DIST) 
INTEGER DEPTH , DIST 
LOGICAL V(,, DEPTH) , W(,, DEPTH) 


3 Description 


The shift is carried out in two stages. If the shift distance is D, then North/South shifting 
is used for that part of the shift given by D modulo 32, and an East shift is used to handle 
the remaining multiples of 32. 


4 References 


None 


5 Arguments 
V ~ LOGICAL MATRIX array of dimension (,, DEPTH) 
© : On entry, V contains the data to be shifted; V is unchanged on exit. 


W - LOGICAL MATRIX array of dimension (,, DEPTH) | 
On exit, W contains the shifted version of the data in V. 


DEPTH — INTEGER 


On entry, DEPTH specifies the dimension of V; that is, the number of planes to be 
shifted (taken modulo 256). DEPTH is unchanged on exit. 


DIST - INTEGER 


On entry DIST specifies the magnitude of the shift (taken modulo 1024). DIST is un- 
changed on exit. 


6 Error Indicators 


None 


7 Auxiliary Routines 
None 


8 Accuracy 
Not applicable 


9 Further Comments 


None 
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10 Keywords 
Shifting 


li 


276 


Example 
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The example compares the result from X05.SHRP.LV with that from the built-in function 
SHRP. The number of positions at which the two results disagree is counted and displayed. 


Host program 


1000 


PROGRAM MAIN 
COMMON /ICOUNT/ICOUNT 

CALL DAPCON(? ent.dd’) 

CALL DAPENT(’ENT? ) 

CALL DAPREC(?ICOUNT?’ , ICOUNT, 1) 
CALL DAPREL 

WRITE(6,1000) ICOUNT 

FORMAT(? ICOUNT =’ ,I5) 

STOP 

END 


DAP program 


ENTRY SUBROUTINE ENT 
INTEGER IM(,),JM(,),KM(,) 
COMMON /ICOUNT/ICOUNT 

CALL XO5_LONG_INDEX(IM, 1) 
CALL X05_SHRP_LV(IM, JM,32,99) 
KM=SHRP (IM, 99) 
ICOUNT=SUM(KM.NE. JM) 

CALL CONVSFI(ICOUNT, 1) 

RETURN 

END 


Results 


ICOUNT = 0 
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1 Purpose 


X05.SOUTH _ BOUNDARY returns a logical matrix containing at most one .TRUE. in each 
column, corresponding to the last .TRUE. (if any) in each column of the logical matrix 
parameter. That is, the routine is equivalent to the FORTRAN-PLUS code: 


KM = .FALSE. 
DO 101 = 1, 32 
IF (.NOT. ANY (LM(,I))) GOTO 10 
KM(,I) = REV(FRST (REV (LM (,1)))) 
10 CONTINUE 
2 Specification 


LOGICAL MATRIX FUNCTION X05:SOUTH - BOUNDARY (LM) 
LOGICAL LM(,) 


3 Description 


The DAP store plane (logical matrix LM) passed to the routine is treated as a set of 32 
logical vectors, arranged so that each vector occupies a complete column. Each of these 
vectors is dealt with independently, but in parallel. 


To each vector is ripple-added a column of all-true bits; the southernmost bit of the vector is 
treated as least significant. The addition is thrown away; the column of carry bits from the 
addition, and a shifted-north version of the column of carries, are XORed to give a vector 

© with only one true element: the southernnmost .TRUE. element in each input vector. The 
32 resultant vectors, produced in parallel, form the required south boundary matrix. 


4 References 


None 


5 Arguments 


LM — LOGICAL MATRIX 
On entry, LM is the logical matrix whose south boundary is required. LM is unchanged 


on exit. 


6 Error Indicators 


None 


7 Auxiliary Routines 


None 


8 Accuracy 
Not applicable 


9 Further Comments 


None 
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10 Keywords 





Boundary 


11 Example 


The following FORTRAN-PLUS fragment takes a ‘black and white’ logical matrix (a chess 
board pattern) as input, and returns the south boundary. 


ENTRY SUBROUTINE ENT 
LOGICAL LM(,),KM(,) 

EXTERNAL LOGICAL MATRIX FUNCTION X05_SOUTH_BOUNDARY 
LM=ALTR(1). LEQ. ALTC(1) 

KM=X05_SOUTH_BOUNDARY (LM) 

TRACE 1 (KM) 

RETURN 

END 


The result in this case is simply LM .AND. ROWS (31,32) 
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10 


11 


Purpose 


X05.STRETCH -4 stretches the first quarter of a real matrix A (considered as a long vector), 
such that each element is repeated four times consecutively. 


Specification 


REAL MATRIX FUNCTION X05_STRETCH 4(A) 
REAL A (,) 


Description 


The routine uses a recursive doubling algorithm to re-arrange the data. 


References 


None 


Arguments 


A - REAL MATRIX 


On entry, the first 256 elements of A must be defined. On exit, the 1024 elements of 
A contain 256 groups of 4 identical elements, the groups being one elements repeated 4 
times, from each of the first 256 elements of the input matrix; long vector order is used. 


_ Error Indicators 


None 


Auxiliary Routines 


None 


Accuracy 
Not applicable 


Further Comments 


None 


Keywords 


Data manipulation 


Example 


The following FORTRAN-PLUS fragment sets up an index matrix such that A(I) =I 
(I = 1, 2,... 256), with other elements being undefined. This matrix is then ‘stretched’ 
so that: 


a= ay for I= 1,2,... 1024 
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ENTRY SUBROUTINE ENT 
REAL AC,) 

INTEGER IM(,) 

EXTERNAL REAL MATRIX FUNCTION XO5_STRETCH_4 
CALL XO5_LONG_INDEX (IM, 1) 

ACELSL(1,256)) = FLOAT(IM) 

A = XO5_STRETCH_4(A) 

RETURN 

END 
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10 
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Purpose 


X05.STRETCH _8 stretches the first eighth of a real matrix A (considered as a long vector), 
such that each element is repeated eight times consecutively. 


Specification 


REAL MATRIX FUNCTION X05.STRETCH _8(A) 
REAL A (,) 


Description 


The routine uses a recursive doubling algorithm to re-arrange the data. 


References 


None 


Arguments 


A —- REAL MATRIX : 
On entry, the first 128 elements of A must be defined. On exit, the 1024 elements of 
A contain 128 groups of 8 identical elements, the groups being one elements repeated 8 
times, from each of the first 128 elements of the input matrix; long vector order is used. 
Error Indicators 


None 


Auxiliary Routines 


None 


Accuracy 
Not applicable 


Further Comments 


None 


Keywords 


Data manipulation 


Example 


The following FORTRAN-PLUS fragment sets up an index matrix such that A(I) =I 
(I = 1, 2,... 128), with other elements being undefined. This matrix is then ‘stretched’ 
so that: 


A= 441 for I=1,2,... 1024 


General Support library man010.02 281 


15.34 X05_STRETCH _8 X05 — Other utilities 


ENTRY SUBROUTINE ENT 

REAL AC(,) 

INTEGER IM(,) 

EXTERNAL REAL MATRIX FUNCTION XOS_STRETCH_8 
CALL XO5_LONG_INDEX(IM, 1) 

ACELSL(1,128)) = FLOAT(IM) 

A = XO5_STRETCH_8(A) 

RETURN 

END 
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15.35 X05_STRETCH _N release 1 


10 


Purpose 


X05.STRETCH _N stretches the first n‘” of a real matrix A (considered as a long vector) 
such that each element is repeated n times consecutively (n= gly, I being a positive integer. 


’ 


Specification 


REAL MATRIX FUNCTION X05.STRETCH _N(A, I, IFAIL) 
REAL A (,) 


Description 


The routine uses a recursive doubling algorithm to re-arrange the data. 


References 


None 


Arguments 


A —- REAL MATRIX 


On entry, the first 1024/n elements of A must be defined. On exit, the 1024 elements of 
A contain 1024/n groups of n identical elements, the groups being one element repeated 
n times, from each of the first 1024/n elements of the input matrix; long vector order is 
used. 


I - INTEGER 
Lis the power of 2, such that n= 21. Tis unchanged on exit 


IFAIL ~ INTEGER 
On exit, IFAIL = 1 if the implied value of n is greater than 32 


Error Indicators 


None 


Auxiliary Routines 


None 


Accuracy 
Not applicable 


Further Comments 


None 


Keywords 


Data manipulation 
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11 Example 


The following FORTRAN-PLUS fragment sets up an index matrix such that A(I) =I 
(I = 1, 2,... 128), with other elements being undefined. This matrix is then ‘stretched’ 
so that: 





A(D= faa for I[=1,2,... 1024 


ENTRY SUBROUTINE ENT 

REAL A(,) 

INTEGER IM(,) 

EXTERNAL REAL MATRIX FUNCTION XOS5_STRETCH_N 
CALL XO5_LONG_INDEX(IM, 1) 

ACELSL(1,128)) = FLOAT(IM) 

A = XO5_STRETCH_N( A,3,IFAIL ) 

trace 1(a) 

RETURN 

END 


Results 


FORTRAN~PLUS Trace 
FORTRAN-PLUS Subroutine: ENT at Line 8 


Real Matrix Local Variable A in 32 bits - addressed by Stack + 0.09 





.0000000E+00, 


(Row 01 Col 01) 1 5.QQ000000E+00, 9.0000000E+00, 
(Row 02 Col 01) 1.0000000E+00, 5.0000000E+00, 9.0000000E+00, 
(Row 03 Col 01) 1.0000000E+00, 5.0000000E+00, 9.0000000E+00, 
(Row 04 Col 01) 1.0000000E+00, 5.0000000E+00, 9.0000000E+00, 
(Row 05 Col 01) 1.0000000E+00, 5.0000000E+00, 9.0000000E+00, 
(Row 06 Col 01) 1.0000000E+00, §5.0000000E+00, 9.0000000E+00, 
(Row 07 Col 01) 1.0000000E+00, 5.0000000E+00, 9.0000000E+00, 
(Row 08 Col 01) 1.0000000E+00, 5.0000000E+00, 9.0000000E+00, 
(Row 09 Col 01) 2.0000000E+00, 6.0000000E+00, 1.0000000E+01, 
(Row 10 Col 01) 2.0000000E+00, 6.0000000E+00, 1.Q0000000E+01, 
(Row 11 Col 01) 2.0000000E+00, 6.0000000E+00, 1.0000000E+01, 


plus rest of TRACE output... 
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1 Purpose 


X05.SUM.LEFT_I2 takes as input the long vector A (INTEGER* 2) and returns an (IN- 
TEGER* 2) long vector, each of whose elements is the sum of all the clements to the left of 
the corresponding element of A, excluding the element itself. 


2 Specification 


INTEGER* 2 MATRIX FUNCTION X05_SUM_LEFT_I2(A) 
INTEGER* 2 A(,) 


3 Description 


Let A (= Ajj) be the given long vector. The required long vector result S (= Sj;) is given 
By 


~1 32 


Si = >> > ante Axj 


=sll=1 


The sum is broken down into the following steps: 


1 B= » A,j the cumulative sums down each column 
k=1 


@) 2 Cij = Bgej-1 for each i, where Bgoo = 0 


3 Dj= > Cy, the cumulative sums of C along each row 
k=1 


4 Sij = Dij+Bi-15 where Boj =0 


The summations (1) and (3) are performed using standard parallel algorithms (6 steps). The 
remaining operations consist of shifts and a matrix add. 


4 References 


None 


5 Arguments 


A - INTEGER* 2 
On entry, A contains the long vector on which the sum left is to be performed. A is 
unchanged on exit. 


6 Error Indicators 


None 


7 Auxiliary Routines 


None 
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8 Accuracy 


The results are accurate provided there is no overflow. 


9 Further Comments 


None 


10 Keywords 


None 


11 Example 


In the example, a sum-left is performed on an integer long vector with all components equal 
to 1. The first five and last five values of the input and resulting long vectors are printed, in 
long vector order. 


Host program 


PROGRAM HTSL2 


INTEGER*2 ILV1(32,32) , ILV2(32,32) 
COMMON /BDATA/ILV1,ILV2 


CALL DAPCON(’ts12.dd’) 
CALL DAPENT(?TSL2’) 


CALL DAPREC(’BDATA’ , ILV1, 1024) 
CALL DAPREL 


WRITE(6 , 6001) 

WRITE(6,6002) (ILVi(I,1),I=1,5), (ILV1(1I,32) ,I=28,32) 

WRITE(6 , 6003) 

WRITE(6,6004) (ILV2(I,1),I=1,5), (ILV2(I,32) ,I=28,32) 
6001 FORMAT(’INPUT VECTOR’/) 


6002 FORMAT(5(1X,I1),’ . . .’,5(1X,I1)) 
6003 FORMAT(//, ?RESULT’/) 
6004 FORMAT(5(1X,I1),’ . . .?,5(1X,14)) 
STOP 
END 
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DAP program 





ENTRY SUBROUTINE TSL2 


INTEGER*2 ILV1(,),ILV2(,) 
COMMON /BDATA/ILV1,ILV2 


EXTERNAL INTEGER*2 MATRIX FUNCTION XO5_SUM_LEFT_I2 


ILVi=1 
ILV2=X05_SUM_LEFT_I2(ILV1) 


CALL CONVMF2(ILV1) 
CALL CONVMF2(ILV2) 


RETURN 
END 


Results 


INPUT VECTOR 


tTidiit... tiaiia 
RESULT 
01234. . . 1019 1020 1021 1022 1023 
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Purpose 


X05.SUM_RIGHT-_I2 takes as input the long vector A (INTEGER®* 2) and returns an 
(INTEGER* 2) long vector each of whose elements is the sum of all the elements on the 
right of the corresponding element of A. The sum is strict in the sense that the element itself 
is not included. 


Specification 


INTEGER* 2 MATRIX FUNCTION X05.SUM_RIGHT-I2 (A) 
INTEGER* 2 A(,) 


Description 


Let A (= Aj;) be the given long vector. The required long vector result S (= S,;) is given 
by: 


32 32 32 
Sy= YD At Yo An 
k=j+1l=i+1 k=j+1 


The sum is broken down into the following steps: 


32 
1 B= > Aj; the cumulative sums up each column 
l=t41 . 


2 Ci; = Bz2j41 foreachi, where B;33 = 0 


32 
3 Dy= > Ci, the cumulative sums of C along each row (right to left) 
k=j+1 


4 Sj = Dij+Bij41 where Bj 33 = 0 


The summations (1) and (3) are performed using the standard parallel algorithms (6 steps). 
The remaining operations consist of shifts and a matrix add. 


References 


None 


Arguments 
A - INTEGER* 2 


On entry, A contains the long vector on which the sum-right is to be performed. A is 
unchanged on exit. 


Error Indicators 


None 
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7 Auxiliary Routines 





None 


8 Further Comments . 


None 


9 Keywords 


None 


10 Example 


In the example, a sum-right is performed on an integer vector with all components equal to 
1. The first five and last five values of the input and resulting long vectors are printed in 
long vector order. 


Host program 


PROGRAM HTSR2 


INTEGER*2 ILV1(32,32) , ILV2(32,32) 
COMMON /BDATA/ILV1,ILV2 


CALL DAPCON(’tsr2.dd’) 
CALL DAPENT(’TSR2? ) 


© CALL DAPREC(’BDATA?’ , ILV1, 1024) 
CALL DAPREL 


WRITE(6,6001) 

WRITE(6,6002) (ILVi(I,1),I=1,5), (ILV1(1,32) , 1=28,32) 

WRITE(6,6003) 

WRITE(6,6004) (ILV2(I,1),I=1,5), (ILV2(I,32) ,I=28,32) 
6001 FORMAT(’ INPUT VECTOR’ /) 


6002 FORMAT(5(1X,I1),’ . . .*,5(1X,I1)) 
6003 FORMAT(//, RESULT’ /) 
6004 FORMAT(5(1X,I4),’ . . .*,5(1X,I1)) 
STOP 
END 
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DAP program 
ENTRY SUBROUTINE TSR2 


INTEGER*2 ILV1(,),ILV2(,) 
COMMON /BDATA/ILV1,ILV2 


EXTERNAL INTEGER+2 MATRIX FUNCTION XO5_SUM_RIGHT_I2 


ILVi=1 
ILV2=X05_SUM_RIGHT_I2(ILV1) 


CALL CONVMF2(ILV1) 
CALL CONVMF2(ILV2) 


RETURN 
END 


Results 


INPUT VECTOR 


PTiiaiit... ittiii 
RESULT 
1023 1022 1021 1020 1019. ..43210 
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1 Purpose 


X05.UNCRINKLE effects a transformation in data storage format for vertical mode data 
occupying an array of matrices from ‘crinkled’ to ‘sliced’ storage. : 


2 Specification 


SUBROUTINE X05_UNCRINKLE (S, L, NR, NC, IFAIL) 
<any type, any length> S(,,NR,NC) 
INTEGER BL, NR, NC, IFAIL 


3 Description 


The data is conceptually considered to occupy an array C of components of size 32 NR by 
32 NC. (NR or NC are positive integers, not excluding 1). The storage area, S, is an NR by 
NC array of matrices. In the ‘sliced’ format: 


S (i, te, dry je) = Cc (i, +32 (jr—1), Ig +32 (je—-1)) 


that is, each value of j, selects a contiguous group of 32 rows of C, and so on. 


In the ‘crinkled’ format: 
S (ip; te, drs Je) =C (j- +NRi,—1), j-+NC (?-—1))) 


that is, each value of i, selects a contiguous group of NR rows of C, and so on. 


© In the ‘sliced’ format the conceptual array is divided into subarrays of size 32 by 32. In the 
‘crinkled’ format the conceptual array is divided into subarrays of size NR by NC. 


To carry out the transformation, first a mapping transformation is done on East — West 
vertical sections of the data area. Each section is regarded as an array of 32NC data items; 
each item is of length L by NR (vertical) bits. The transformation reverses the mapping 
order so that succesive horizontal sets of NC data items are rethreaded vertically. 


Then a similar transformation is done on NC separate groups of North — South vertical 
sections of the data area. Each section of each group is regarded as an array of 32NR data 
items; each item is of length L (vertical) bits. The transformation reverses the mapping 
order so that successive horizontal sets of NR data items are rethreaded vertically. 


4 References 


None 


5 Arguments 


S — <any type, any length > MATRIX array of dimension (,,NR,NC) 


On entry, S contains the sliced data to be reformatted. On exit, S contains the data in 
crinkled form. 


L - INTEGER 


On entry, L specifies the length in bits of the components of S; L is unchanged on exit. 


NR - INTEGER 


On entry, NR specifies the first unconstrained dimension of S; NR is unchanged on exit. 





General Support library man010.02 291 . 


15.38 X05. UNCRINKLE X05 — Other utilities 


10 


ll 








292 


Arguments - continued 
NC —- INTEGER 


On entry, NC specifies the second unconstrained dimension of S; NC is unchanged on 
exit. 


IFAIL - INTEGER 


Unless the routine detects an error (see Error Indicators below) IFAIL contains zero 
on exit. 


Error Indicators 

Errors detected by the routine: 
IFAIL = 1 either NR or NC was less than 1 
IFAIL = 2 L was less than 1 


Auxiliary Routines 
to be supplied ... 


Accuracy 
Not applicable 


Further Comments 
None 


Keywords 


Crinkled data storage, data formatting, data movement, sliced data storage 


Example 


The following FORTRAN-PLUS fragment shows how the routine can be used in an entry 
subroutine to convert a matrix set from crinkled to sliced form. 


ENTRY SUBROUTINE ENT 

REAL A(,,2,2) 

COMMON /A/A 

DO 10 I=1,2 

DO 10 J=1,2 

CALL CONVFM4(A(,,I,J)) 

10 CONTINUE 

CALL XO5_UNCRINKLE(A,4,2,2,IFAIL) 

IF (IFAIL.NE.O) RETURN 
c DAP processing 

RETURN 

END 
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1 Purpose 


X05.WEST_ BOUNDARY returns a logical matrix containing at most one .TRUE. element 
in each row corresponding to the first .TRUE. (if any) in each row of the logical matrix 
parameter. That is, the subroutine is equivalent to the FORTRAN-PLUS code: 


KM = .FALSE. 
DO 10I = 1, 32 
IF (.NOT. ANY (LM(I,))) GOTO 10 
KM (I,) = FRST (LM (I, )) 
10 CONTINUE 
2 Specification 


LOGICAL MATRIX FUNCTION X05_WEST. BOUNDARY (LM) 
LOGICAL LM (,) 


3 Description 


The DAP store plane (logical matrix LM) passed to the routine is treated as a set of 32 
logical vectors, arranged so that each vector occupies a complete row. Each of these vectors 
is dealt with independently, but in parallel. 


To each vector is ripple-added a row of all-true bits; the westernmost bit of the vector is 
treated as least significant. The addition is thrown away; the row of carry bits from the 

© addition, and a shifted-east version of the row of carries, are XORed to give a vector with 
only one true element: the westernnmost .TRUE. element in each input vector. The 32 
resultant vectors, produced in parallel, form the required west boundary matrix. 


4 References 
None 


5 Arguments 


LM - LOGICAL MATRIX 
On entry, LM is the logical matrix whose west boundary is required. LM is unchanged 
on exit. 


6 Error Indicators 
None 


7 Auxiliary Routines 


None 


8 Accuracy 
Not applicable 


9 Further Comments 
None 
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10 Keywords 
Boundary 


11 Example 


The following FORTRAN-PLUS fragment takes a ‘black and white’ logical matrix (a chess 
board pattern) as input and returns the west boundary. 


ENTRY SUBROUTINE ENT 

LOGICAL LM(,),KM(,) 

EXTERNAL LOGICAL MATRIX FUNCTION XO5_WEST_BOUNDARY 
LM=ALTR(1).LEQ.ALTC(1) 

KM=X05_WEST_BOUNDARY (LM) 

TRACE 1 (KM) 

RETURN 

END 


The result in this case is simply LM .AND. COLS(1,2) 
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